Skip to main content
Version: 1.11

Deployment using Kubernetes

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

You can install K8s in one of the following ways:

🖥️ Local installation using minikube.

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

note

The following describes a suggested approach for Kubernetes deployment. However, you are encouraged to customize your deployment to align with your specific system configuration taking into account potential security concerns and other relevant considerations.

Requirements​

To run ADS 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

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

Preparation​

Access Decision Service is downloaded via AWS CLI. If you have not already done so, install AWS CLI following the instructions in AWS documentation.

Configure the Axiomatics AWS CLI account​

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

Download the ADS distribution​

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

aws s3api get-object --bucket axiomatics-customer-artifacts --key releases/com/axiomatics/access-decision-service/access-decision-service/1.11.0-0/access-decision-service-1.11.0-0.zip access-decision-service-1.11.0-0.zip

Extract the ADS distribution .zip file to the folder from where you want to run ADS.

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:

Create the truststore​

  1. Get the SSL certificate of the gateway that was used for ASM to create the ADS truststore.jks.

  2. Create the truststore.jks from the .crt file and add it to your docker image.

    note

    For the creation of the truststore file, convert the certificate file that you used during the installation of ASM.

    Use the following command to convert the .crt file to .jks:

    keytool -importcert -deststorepass changeit -keystore truststore.jks -file server.crt -alias 1 -noprompt -storetype JKS

  3. Add the truststore.jks file to the ADS docker/resources/ folder.

Login to your Docker registry​

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. 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

  2. Create the following repositories in your ECR registry:

    axiomatics/ads

Build the Docker images​

  1. Navigate to the ADS docker folder of the extracted distribution.

  2. Edit the credentials.txt file by updating 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.

  3. Copy a valid PDP license file to the docker directory.

    note

    This file is provided separately by Axiomatics.

  4. To add one or more Attribute Connectors download the respective jar files and navigate to resources/lib/. Place them under the lib folder as shown in the structure tree below:

    ├─ lib/
        ├─ <attribute-connector-1>.jar
        ├─ <attribute-connector-2>.jar

    Additional files, such as JDBC drivers (should they be necessary), must be also added under the lib folder, in the same way as Attribute Connectors.

    For updating one or more existing Attribute Connector(s), refer to section Update Attribute Connector(s) for Kubernetes deployment.

Run the following command to build ADS.

docker build --build-arg AWS_BUCKET=axiomatics-customer-artifacts --build-arg AWS_REPO=releases --build-arg ADS_VERSION=1.11.0 . -f Dockerfile -t <aws_account_id>.dkr.ecr.<region>.amazonaws.com/axiomatics/ads:1.11.0

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

docker push <aws_account_id>.dkr.ecr.<region>.amazonaws.com/axiomatics/ads:1.11.0
Important

Replace the version placeholders with the most recent available distribution.

Setup​

This section describes how to deploy Kubernetes with ADS.

You can install Kubernetes with ADS in one of the following ways:

  • Local installation using minikube.
  • Cloud installation using EKS from AWS.

Follow the steps below according to your specific setup:

Installation procedure​

  1. Navigate to the kubernetes directory.

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

  2. If minikube is not already running follow the commands below to start minikube.

    1. Start minikube:

      minikube start

    2. 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.

  3. On the initial terminal window, create the ADS namespace.

    kubectl create namespace axiomatics-ads

Create secrets​

  1. Create a secret for the Keycloak client. Use your own client id and secret, which can be found on the Keycloak dashboard. 

    kubectl create secret generic ads-adm-access-secret \
    --from-literal=client-id=<client_id> \
    --from-literal=client-secret=<secret>  \
    --from-literal=client-token-uri=https://<asm_hostname>/auth/realms/asm/protocol/openid-connect/token \
    --namespace=axiomatics-ads
    note

    In case of local installation <asm_hostname> = host.docker.internal

    For more information on how to use Keycloak with ADS, please refer to Configure Keycloak for ADS.

  2. 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 --region=<region_code>) \
    --namespace=axiomatics-ads

  3. Create an ADS License secret.

    kubectl create secret generic ads-license \
    --from-file=axiomatics_PDP.license \
    --namespace axiomatics-ads

  4. Create a secret for the ADS PEP credentials:

    kubectl create secret generic ads-pep-client-login --from-literal=username=ads-user --from-literal=password=2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b --namespace=axiomatics-ads
    note

    The default password is secret encrypted in SHA256 hash.

    You can change your password with the following command:

    echo -n yourPassword | sha256sum

Final steps​

  1. Navigate to the kubernetes directory and install ADS using Helm. 

    helm install -n axiomatics-ads ads -f adscharts/values.yaml adscharts --set imageRegistry=<your_image_registry> --set adsHostname=<your_hostname> --set asmHostname=<your_asm_hostname> --set admDomainName=<your_adm_domain_name> --set asmProjectName=<your_asm_project_name> --set ads.metrics.enabled=true
    Important

    In the command above, replace the placeholders with your own values. For details, see the table below.

    ParameterValueDescription
    imageRegistry<your_image_registry>The remote image registry. For example, the ECR IP
    <aws_account_id>.dkr.ecr.<region_code>.amazonaws.com/axiomatics/
    adsHostname<your_hostname>The hostname you use.
    asmHostname<your_asm_hostname>The hostname of your ASM.
    For local installation, use host.docker.internal.
    asmProjectName<your_asm_project_name>The name of your ASM project.
    admDomainName<your_adm_domain_name>The domain name of ADM.
    ads.metrics.enabledtrue or falseSet this parameter to true if you want to send metrics to the ASM Dashboard.
    The default value is false.

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

    kubectl get all -n axiomatics-ads

Troubleshooting​

Extra commands that can assist your troubleshooting efforts.

note

In the snippets below replace

  • <region-code> with your cluster's AWS Region
  • <aws_account_id> with your AWS account ID

Minikube with -p/--profile​

The name of the minikube VM being used to allow having multiple instances of minikube independently.

minikube start -p axiocube
minikube tunnel -p axiocube
minikube stop -p axiocube

Image pull policy​

If the pod already exists with the IfNotPresent pull policy and has failed, restart it.

kubectl rollout restart deploy ads -n axiomatics-ads

Kubernetes statuses​

ImageErrPull​

If the job fails with ImageErrPull because of an expired registry credentials secret

  1. Delete secret.

    kubectl delete secret  regcred -n axiomatics-ads

  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-ads