Deploy on Kubernetes

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

note

The following is a suggested approach for K8s deployment. Customize it to match your system configuration, security requirements, and operational practices.

Requirements

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

• kubectlOpens in a new tab

  The 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

  Required only if pulling the ADS image from the Axiomatics ECR.

• DockerOpens in a new tab

  Required only if building a custom image.

note

The instructions below assume ADS starts with a basic configuration. See Basic configuration for more information.

Step 1: Prepare your image

To deploy ADS in K8s, you need a Docker image. Choose one of the following options:

• Axiomatics image

  A ready-to-use image from the Axiomatics ECR that includes the standard Attribute Connectors (SQL, Table, LDAP, HTTP, and Parser). This image does not include additional drivers, such as JDBC drivers required by the SQL and Table Attribute Connectors. If you need custom drivers, build your own image and include them manually as described below.

• Custom image

  Build your own image to include additional drivers or custom Attribute Connectors.

• Axiomatics image
• Custom image

1. Configure your AWS CLI account using aws configure, as described in the AWS documentationOpens in a new tab. You need an Access key ID and a Secret access key provided by Axiomatics.

2. Log in to the Axiomatics ECR registry:

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

3. Create a registry secret so that K8s can pull the image at deployment time:

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

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

2. Open credentials.txt and replace the placeholder values for Access Key ID and Secret Access Key with the credentials provided by Axiomatics.

   tip

   These are the same credentials you use when setting up AWS CLI.

3. Place any .jar files, such as JDBC drivers or custom Attribute Connectors, into resources/lib/:

   ├─ lib
      ├─ <driver>.jar
      ├─ <custom-attribute-connector>.jar

   See Attribute connectors for more information.

4. Build the image:

   docker build -t <your_custom_registry>/ads:26.2.1-0 .

5. Push the image to your registry:

   docker push <your_custom_registry>/ads:26.2.1-0

Step 2: Run the base deployment

Navigate to kubernetes/charts and copy your axiomatics_ADS.license file into that directory.

The helm install command is built from a base and extended with flags for your domain source, authentication method, and any optional features. Start with the base command below, then add flags from steps 3 and 4 as needed.

note

Replace all angle-bracket placeholders (for example, <aws_account_id>) with your own values before running any command.

tip

The values.yaml and values-*.yaml files supplied in the Helm chart are baseline configurations. Edit them directly to override defaults, add environment-specific settings, or remove options that do not apply to your setup. Any value you set using --set on the command line takes precedence over the same value in a file.

• Axiomatics ECR
• Custom registry

helm install ads \
  -f ads/values.yaml \
  -f ads/<DOMAIN_VALUES_FILE> \
  ads/ \
  --set licenseValue=$(cat axiomatics_ADS.license | base64 -w 0) \
  --set image.repository=<aws_account_id>.dkr.ecr.<region>.amazonaws.com/axiomatics/ads \
  --set 'imagePullSecrets[0].name=regcred'

Replace <aws_account_id> and <region> with your AWS account ID and the target AWS region.

helm install ads \
  -f ads/values.yaml \
  -f ads/<DOMAIN_VALUES_FILE> \
  ads/ \
  --set licenseValue=$(cat axiomatics_ADS.license | base64 -w 0) \
  --set image.repository=<your_custom_registry>/ads

Replace <your_custom_registry> with the path to the repository hosting your ADS image.

Replace <DOMAIN_VALUES_FILE> and add --set flags as described in step 3.

Step 3: Configure your domain source

ADS needs an authorization domain at startup. Add the values file and flags that match your domain setup.

• Remote domain
• Local domain

Use this method when ADS retrieves the domain dynamically from ADM, ASM, or another HTTP endpoint. This is the typical approach for production environments.

Copy your truststore.jks file into kubernetes/charts if the remote endpoint uses TLS (see TLS configuration for Kubernetes).

Replace <DOMAIN_VALUES_FILE> in the base command with the values file for your authentication method:

• OAuth2 / token (recommended): values-fetch-domain-from-adm-token-auth.yaml
• Basic: values-fetch-domain-from-adm-basic-auth.yaml

Add the corresponding --set flags:

• OAuth2 / token
• Basic authentication

--set domain.path=<remote_domain_url> \
--set spring.security.oauth2.client.provider.hub-adm-client.token-uri=<token_endpoint_uri> \
--set secret.admClientId=<oauth2_client_id> \
--set secret.admClientSecret=<oauth2_client_secret>

--set domain.path=<remote_domain_url> \
--set secret.domainUsername=<username_for_basic_auth> \
--set secret.domainPassword=<password_for_basic_auth>

Use this method when you have a static domain.yaml file. Copy it into kubernetes/charts.

Replace <DOMAIN_VALUES_FILE> with values-fetch-domain-from-file.yaml and add the following flag:

--set domainValue=$(cat domain.yaml | base64 -w 0)

Step 4: Optional features

The following features are not required for a basic deployment but improve performance and scalability in production environments.

Configure TLS for the domain connection

For TLS setup, see TLS configuration for Kubernetes.

Distributed caching

Distributed caching enables multiple ADS pods to share cached attribute values across the cluster. Add the following flag to your helm install command:

-f ads/values-distributed-cache.yaml

See Attribute caching for details on how distributed caching works.

Virtual Threads

Java Virtual Threads (Java 21+) are enabled by default in ADS and improve throughput for I/O-bound workloads, particularly when Attribute Connectors are active. To disable them, add the following to values.yaml:

spring:
  threads:
    virtual:
      enabled: false

Full example

The following command deploys ADS using the Axiomatics ECR image, a remote domain with OAuth2 authentication, one-way TLS, and distributed caching:

helm install ads \
  -f ads/values.yaml \
  -f ads/values-fetch-domain-from-adm-token-auth.yaml \
  -f ads/values-fetch-domain-from-adm-tls.yaml \
  -f ads/values-distributed-cache.yaml ads/ \
  --set licenseValue=$(cat axiomatics_ADS.license | 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=<adm_client_token_uri> \
  --set secret.admClientId=<adm_client_id> \
  --set secret.admClientSecret=<adm_client_secret> \
  --set truststoreValue=$(cat truststore.jks | base64 -w 0) \
  --set secret.truststorePassword=<your_truststore_password> \
  --set 'imagePullSecrets[0].name=regcred'

Verify the deployment

After deployment, confirm ADS is running:

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

To access ADS locally, forward the pod port:

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

Update the deployment

To apply changes to your values.yaml without rebuilding the image, upgrade the Helm charts using the same flags as in your helm install command:

helm upgrade ads -f ads/values.yaml ...

If you modify the service configuration (for example, by adding a new property), restart the deployment:

kubectl rollout restart deployment.apps/ads

Next steps

• Enable caching to improve performance: Configure caching
• Review advanced configuration options: Configure ADS
• Configure TLS for domain connections: TLS configuration for Kubernetes