Skip to main content
Version: 7.2

Installation using Kubernetes

This section describes how to deploy ASM using Kubernetes (K8s).

note

The instructions below refer to a fresh installation of ASM.

You can install K8s in one of the following ways:

🖥️ Local installation using minikube.

☁️ Cloud installation using EKS by Amazon Web Services (AWS).

Requirements​

To run ASM locally on a K8s minikube environment, install:

  • Kubernetes and kubectl

    The open-source system for automating deployment, scaling, and management of containerized applications along with its command line tool.

  • minikube

    Local K8s for macOS, Linux, and Windows.

  • AWS CLI

    The official command line interface to manage AWS services.

  • Helm

    The package manager for K8s.

  • Docker and Docker Compose

    The open platform to package and run applications in isolated containers along with the tool for defining and running multi-container Docker applications.

Preparation​

Axiomatics Services Manager is downloaded via AWS CLI. If you have not already done so, install AWS CLI following the instructions in AWS documentation.

  1. Configure the Axiomatics AWS CLI account using the aws configure command, as explained in the AWS documentation. This procedure requires an Access key ID and a Secret access key, which will have been provided to you by Axiomatics.

    tip

    Optionally, you can create and use profiles to store these settings, as described here. This could come in handy in deployments using a remote registry which requires an additional AWS CLI account from your side.

  2. The ASM distribution is downloaded as a ZIP file, containing a pre-configured Docker-based installation. Run the following command in the terminal to download ASM:

    aws s3api get-object --bucket axiomatics-customer-artifacts --key releases/com/axiomatics/axiomatics-services-manager/axiomatics-services-manager/7.2.0-0/axiomatics-services-manager-7.2.0-0.zip axiomatics-services-manager-7.2.0-0.zip
    Important

    Replace the version placeholders with the most recent available distribution.

Docker registry​

The Docker registry is a server side application that stores and lets you distribute Docker images. Axiomatics recommends working with a remote registry both for local and cloud installations. However, for local installations only, if a remote registry cannot be supported by your specific setup, then you can deploy a local registry server.

Follow the steps below according to your specific setup:

Important

In the snippet below replace

  • <region_code> with the AWS Region that you want to create your cluster in
  • <aws_account_id> with your AWS account ID

  1. Configure your AWS CLI account using the aws configure command, as explained in the AWS documentation.

  2. Log in to your Amazon ECR registry.

    aws ecr get-login-password --region <region_code> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region_code>.amazonaws.com

  3. Create the following repositories in your ECR registry, as described in the AWS documentation:

    axiomatics/adm
    axiomatics/api-gateway
    axiomatics/asm-core
    axiomatics/postgres
    axiomatics/influxdb
    axiomatics/pd-api
    axiomatics/pd-ui
    axiomatics/keycloak-mappers
    axiomatics/service-aggregator

Build the Docker images​

  1. Extract the ASM distribution ZIP file to the folder from where you want to run ASM.

  2. Navigate to the docker folder of the extracted distribution.

    1. Open the credentials.txt file and update the placeholder values for Access key ID and Secret access key with the values provided by Axiomatics.

      note

      These are the same values that were used in setting up AWS CLI.

    2. Open the .env file and add your registry.

      REGISTRY=<aws_account_id>.dkr.ecr.<region_code>.amazonaws.com/axiomatics/

    3. Optionally, for deployments that include Access Decision Service (ADS):

      Add your hostname

      Open the .env file and update the values of HOST and CERTIFICATE_CN with your own hostname.

      note

      In case you are working with localhost, use the special domain host.docker.internal.

  3. Enable the BuildKit feature of Docker:

    $Env:DOCKER_BUILDKIT=1

  4. If you will be using Policy Designer, open the docker/docker-compose.yml file and set the following:

    Add the alias of the IdP to be used by Policy Designer

    This is required only if you will be using Policy Designer.

    ParameterValue
    PD_IDP_NAMEThe alias of the IdP that will be set up later in Keycloak to work with Policy Designer. Learn more about the Policy Designer Keycloak configuration.
    The default is "google". Other available options:
    User-defined
    - OpenID Connect v1.0: Make sure that you use the same alias both here and in Keycloak!
    - Keycloak OpenID Connect: Make sure that you use the same alias both here and in Keycloak!
    Social
    - GitHub: "github"
    - Facebook: "facebook"
    - LinkedIn: "linkedin"
    - Instagram: "instagram"
    - Microsoft: "microsoft"
    - BitBucket: "bitbucket"
    - Twitter: "twitter"
    - Openshift v4: Make sure that you use the same alias both here and in Keycloak!
    - Openshift v3: Make sure that you use the same alias both here and in Keycloak!
    - GitLab: "gitlab"
    - StackOverfIow: "stackoverflow"
    Note: SAML is not supported.
    Important: The value should be in lowercase and enclosed in double quotation marks.
    Important: The IdP cannot be changed after the installation process is complete.
    Apply your branding to Policy Designer (optional)

    Optionally, if you want to apply your own branding to the Policy Designer interface, you should also set the following:

    ParameterValue
    PD_LOGOThe path to the logo image file displayed in the upper left corner of the Policy Designer interface.
    The default is "./assets/logo.svg" and the file contains the Axiomatics logo.
    Important: If changed, the value should be an absolute URL pointing to a JPG/JPEG, PNG, or SVG file. For example, "https://www.example.com/assets/your_logo.svg"
    It is recommended that the image resolution is 210x50 pixels.
    PD_APP_NAMEThe app name/title displayed next to the logo and on the browser window.
    The default is "Policy designer".
    Important: The limit is 100 characters.
    PD_MAIN_COLORThe main color used in the Policy Designer interface, for buttons and highlighted components.
    The default is "#0274C1".
    Important: Replacement colors should be in hexadecimal notation.
    PD_BACKGROUND_COLORThe background color used in the Policy Designer interface.
    The default is "#F2F5F8".
    Important: Replacement colors should be in hexadecimal notation.

  5. Run the following command to build ASM.

    docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml build

Push the image to your registry​

Run the following command to push the image to your registry.

docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml push

ASM K8s installation​

  1. Navigate to the kubernetes directory.

    Add the axiomatics_ASM.license license file and launch a terminal window in this directory.

  2. Run the following command to start minikube.

    minikube start
    #In case the system is slow, use the following command instead:
    minikube start --memory 4096

  3. After minikube has started, launch a new terminal window and create a tunnel.

    minikube tunnel
    Important

    This terminal window should remain open during the K8s installation.

  4. On the initial terminal window, create the ASM namespace.

    kubectl create namespace axiomatics-asm

Create secrets​

  1. Create a Kubernetes database secret.

    Important

    Replace the placeholders for the database user, password, and host URL with your own.

    kubectl create secret generic db-connection \
    --from-literal=dbuser=<db_user> \
    --from-literal=dbpassword=<db_password> \
    --from-literal=dbhost=<db_endpoint> \
    --from-literal=dbport=5432 \
    --from-literal=adm_dbname=domain_manager \
    --from-literal=keycloak_dbname=keycloak \
    --from-literal=asm_dburl=postgresql://db:5432/asm \
    --namespace=axiomatics-asm

  2. Create an ADM credentials secret.

    kubectl create secret generic adm-credentials \
    --from-literal=admApiAuthUsername=admin \
    --from-literal=admApiAuthPassword=secret -n axiomatics-asm

  3. Create a Keycloak credentials secret.

    kubectl create secret generic keycloak-credentials \
    --from-literal=keycloakUser=admin \
    --from-literal=keycloakPassword=admin -n axiomatics-asm

  4. Create a secret for pulling from ECR.

    Important

    This applies only to installations using a remote Docker registry.

    kubectl create secret docker-registry regcred \
    --docker-server=<aws_account_id>.dkr.ecr.<region_code>.amazonaws.com \
    --docker-username=AWS --docker-password=$(aws ecr get-login-password) \
    --namespace=axiomatics-asm

  5. Create an ASM License secret.

    kubectl create secret generic asm-license \
    --from-file=axiomatics_ASM.license \
    --namespace axiomatics-asm

Final steps​

You can deploy ASM with the Dashboard functionality enabled or disabled.

  1. Follow the steps below according to your specific setup:

    Navigate to the kubernetes directory and install ASM using Helm.

    Important

    Replace the placeholders with your own values. For details, see the table below.

    helm install -n axiomatics-asm asm -f asmcharts/values.yaml asmcharts --set imageRegistry=<your_image_registry> --set asmHostname=<your_asm_hostname>
    tip

    Store this command in a TXT file for future reference, such as when upgrading to a later version of ASM or in case you want to enable cluster-level logging.

    PlaceholderValue
    <your_image_registry>The image registry:
    For local registry: host.docker.internal:5000
    For remote registry:<aws_account_id>.dkr.ecr.<region_code>.amazonaws.com/axiomatics/
    <your_asm_hostname>The hostname assigned to the instance running ASM. The default is localhost.

  2. List all pods and make sure they are all running.

    kubectl get all -n axiomatics-asm

Troubleshooting​

Extra commands that could assist your troubleshooting effort.

Important

In the snippets below replace

  • <region_code> with your cluster's AWS Region
  • <aws_account_id> with your AWS account ID

Kubernetes statuses​

ErrImagePull

If the pod status is ErrImagePull because of an expired registry credentials secret:

  1. Delete secret.
    kubectl delete secret regcred -n axiomatics-asm
  2. Recreate it.
    kubectl create secret docker-registry regcred --docker-server=<aws_account_id>.dkr.ecr.<region_code>.amazonaws.com --docker-username=AWS --docker-password=$(aws ecr get-login-password) --namespace=axiomatics-asm

ImagePullBackOff

The status ImagePullBackOff means that the ECR Docker image is too large and cannot be downloaded. To resolve this issue, use the following commands to download the required image within minikube.

Important

Replace the placeholders with the appropriate values before running the commands.

minikube ssh
su - root # Default password is 'root'
apt-get update
apt-get install unzip  
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install 
aws configure # Provide AWS Access Key ID and AWS Secret Access Key
aws ecr get-login-password --region <region_code> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region_code>.amazonaws.com
docker pull <aws_account_id>.dkr.ecr.<region_code>.amazonaws.com/axiomatics/asm-core:<version>

What's next?​

Add users​

During the deployment, a Keycloak service was also installed, to serve as an authentication module for the users of ASM. Only a default administrative user is created automatically at this time. All other users must be created and assigned a role in Keycloak, before they can log in to ASM.

To add more users and map them to roles you must use Keycloak as described in Manage users in Keycloak. Then, you can assign them to projects following the instructions in the Users and projects topic.

Important

For deployments with Policy Designer, you should also configure Keycloak accordingly.

Additional configuration​

Once the installation of ASM has been verified as successful, there are additional configurations you may want to consider.