Skip to main content
Version: 2.2

Deployment using Kubernetes

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

note

The following is a suggested approach for K8s deployment. However, we encourage you to customize it to align with your specific system configuration, considering potential security concerns and other relevant factors.

Requirements​

To deploy ADS in a K8s environment, you'll need the following tools:

  • kubectlOpens in a new tab

    The official command line tool for communicating with a K8s cluster.

  • HelmOpens in a new tab

    The package manager for K8s.

  • AWS CLIOpens in a new tab

    The official command line interface to manage AWS services.

  • DockerOpens in a new tab

    The open platform to package and run applications in isolated containers.

Deployment overview​

Here’s a high-level guide to deploying ADS 2.x in Kubernetes:

  1. Prepare your environment

    1. Install required tools (Docker, AWS CLI, K8s, Helm, etc.)

    2. Configure a Docker registry (remote or local)

      Set up AWS CLI credentials if pulling from Axiomatics' ECR registry

  2. Build or fetch your Docker image

    Pull the prebuilt image from Axiomatics’ ECR or build your own with custom drivers or Attribute Connectors

  3. Prepare K8s (optional)

    1. Add a secret for registry access (if applicable)
    2. Set up truststore and domain file (if needed)

  4. Run ADS

    Deploy ADS using Helm charts

info

You can find detailed instructions for each step below. Choose the path that matches your environment and setup.

Prepare the environment​

The prebuilt ADS image is accessible from the Axiomatics ECR. If you want to create a custom image you need to set up your own Docker registry.

Select your ADS image​

To deploy ADS in K8s, you need a Docker image. You have the following two options to obtain one:

  • Axiomatics image

    Axiomatics provides a ready-to-use image through the Axiomatics ECR which includes the standard Attribute Connectors (SQL, Table, LDAP, HTTP, and Parser).

    note

    The ECR image doesn't include additional drivers, such as JDBC drivers required by the SQL and Table attribute connectors. If you need custom drivers, you must build your own image and include them manually as described below.

  • Custom image

    Alternatively, you can build your own image and push it to any registry you prefer.

If you choose to use the Axiomatics image, follow the steps below:

  1. Configure the Axiomatics AWS CLI account using the aws configure command, as explained in the AWS documentationOpens in a new tab. This procedure requires an Access key ID and a Secret access key provided by Axiomatics.

  2. Log in to the Amazon ECR registry provided by Axiomatics.

    aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin 748131003707.dkr.ecr.eu-central-1.amazonaws.com

  3. Create a Docker registry secret to allow K8s to pull the image from the Axiomatics ECR registry during deployment.

    kubectl create secret docker-registry regcred \
    --docker-server=748131003707.dkr.ecr.eu-central-1.amazonaws.com \
    --docker-username=AWS \
    --docker-password=$(aws ecr get-login-password)

Deploy ADS​

You can deploy ADS using K8s in one of the following ways:

  • Remote domain

    ADS pulls the domain dynamically from ADM/ASM or any other endpoint. This is typically used in production or cloud-based setups.

  • Local domain

    The domain configuration remains static and self-contained. Use this method if you have a domain.yaml file prepared.

Follow the steps below according to your specific scenario:

To deploy ADS using a remote domain:

  1. Navigate to kubernetes/charts and perform the following actions:

    1. Copy the axiomatics_ADS.license file into this directory.
    2. Generate the corresponding truststore.jks file and store it in this location.

  2. Install the ADS chart using Helm according to your specific setup.

note

The following commands use token-based authentication to fetch domain data. However, you can also retrieve the domain from the remote endpoint using basic authentication. This setup is particularly relevant for the integration scenario with ASM, for retrieving domain from ASM domain management API. See Retrieve domain using Basic authentication for more information.

Important

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

helm install ads 
  -f ads/values.yaml 
  -f ads/values-fetch-domain-from-adm-token-auth.yaml ads/ 
  --set licenseValue=$(cat axiomatics_ADS.license | base64 -w 0) 
  --set truststoreValue=$(cat truststore.jks | base64 -w 0)
  --set image.repository=<aws_account_id>.dkr.ecr.<region>.amazonaws.com/axiomatics/ads 
  --set domain.path=<your_domain_path> 
  --set spring.security.oauth2.client.provider.hub-adm-client.token-uri=<your_token_uri>
  --set secret.admClientId=<your_client_id>
  --set secret.admClientSecret=<your_adm_secret> 
  --set secret.truststorePassword=<your_truststore_password>
  --set imagePullSecrets[0].name=regcred
PlaceholderDescription
<aws_account_id> and <region>Your AWS account ID and the AWS region that you want to create your cluster in.
<your_domain_path>Path to the remote ADM domain.
<your_token_uri>The token URI for authenticating to ADM.
<your_client_id> and <your_adm_secret>ADM credentials for token exchange.
<your_truststore_password>The truststore password.

Additional features​

The following features are not required for a basic deployment but can enhance performance, scalability, and flexibility in production environments.

Retrieve domain using Basic authentication​

For integration scenarios using a standalone ADM, you can configure your ADS K8s deployment to retrieve the domain from a remote endpoint using Basic authentication. To do so, install the ADS chart using Helm as shown below.

You can retrieve your domain from a standalone ADM without TLS.

Important

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

helm install ads 
-f ads/values.yaml 
-f ads/values-fetch-domain-from-adm-basic-auth.yaml ads/ 
--set licenseValue=$(cat axiomatics_ADS.license | base64 -w 0) 
--set truststoreValue=$(cat truststore.jks | base64 -w 0)
--set image.repository=<aws_account_id>.dkr.ecr.<region>.amazonaws.com/axiomatics/ads 
--set domain.path=<your_domain_path> 
--set secret.domainUsername=<your_domain_username>
--set secret.domainPassword=<your_domain_password>
--set imagePullSecrets[0].name=regcred
PlaceholderDescription
<aws_account_id> and <region>Your AWS account ID and the AWS region that you want to create your cluster in.
<your_domain_path>Path to the remote ADM domain.
<your_domain_username>The username for Basic authentication.
<your_domain_password>The password for Basic authentication.

Update configuration during runtime​

Modify the values.yaml file to update Helm values by editing or adding properties. Apply these changes without rebuilding the image by running a helm upgrade command according to your scenario as shown in the sample below:

Helm upgrade scenarios
To upgrade ADS using a remote domain:
Important

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

helm upgrade ads 
  -f ads/values.yaml 
  -f ads/values-fetch-domain-from-adm-token-auth.yaml ads/ 
  --set licenseValue=$(cat axiomatics_ADS.license | base64 -w 0) 
  --set truststoreValue=$(cat truststore.jks | base64 -w 0)
  --set image.repository=<aws_account_id>.dkr.ecr.<region>.amazonaws.com/axiomatics/ads 
  --set domain.path=<your_domain_path> 
  --set spring.security.oauth2.client.provider.hub-adm-client.token-uri=<your_token_uri>
  --set secret.admClientId=<your_client_id>
  --set secret.admClientSecret=<your_adm_secret> 
  --set secret.truststorePassword=<your_truststore_password>
  --set imagePullSecrets[0].name=regcred
PlaceholderDescription
<aws_account_id> and <region>Your AWS account ID and the AWS region that you want to create your cluster in.
<your_domain_path>Path to the remote ADM domain.
<your_token_uri>The token URI for authenticating to ADM.
<your_client_id> and <your_adm_secret>ADM credentials for token exchange.
<your_truststore_password>The truststore password.

If the service configuration is modified (for instance, by adding a new property), you'll need to perform a restart using the following command:

kubectl rollout restart deployment.apps/ads

Enable distributed caching​

The distributed cache feature enables multiple ADS pods to replicate and share attribute cache entries across the cluster, enhancing high availability and scalability. To enable distributed cache for your pods, add the following flag to your deployment's initiation command:

-f ads/values-distributed-cache.yaml ads/

For example:

helm install ads -f ads/values.yaml
-f ads/values-fetch-domain-from-file.yaml 
-f ads/values-distributed-cache.yaml ads/ 
--set licenseValue=$(cat axiomatics_ADS.license | base64 -w 0) 
--set domainValue=$(cat domain.yaml | base64 -w 0)

Virtual Threads​

Java Virtual Threads, introduced in Java 21, are a lightweight concurrency mechanism designed to improve application performance and scalability. This feature is enabled by default in ADS and is especially beneficial for I/O-bound workloads, such as when attribute connectors are included in the domain.

You can control this functionality through values.yaml. To disable it, set the following property:

spring:
  threads:
    virtual:
      enabled: false

Verify your deployment​

After deployment, you can verify that ADS is running:

kubectl get pods
kubectl logs <ads-pod-name>

You can also forward your pods' ports to access them locally:

kubectl port-forward  <ads-pod-name> 8080:8888

Next steps​

  • The instructions above assume ADS is started with a basic configuration. See the section Deployment configuration for more information.
  • Consider using the ADS caching features to further improve system performance. See the Attribute caching section for more information.
  • There are also additional configurations you may want to consider for your implementation of ADS. See the section Additional configurations for more information.