Install a Kubernetes Edge with Helm

This guide describes how to install a Kubernetes edge on an Azure Kubernetes Service (AKS) cluster using the local-edge Helm chart, and how to verify, upgrade, and uninstall it.

See Kubernetes Edge for an overview of the Kubernetes edge and the deployment steps, and Edge Processing for background on edge processing and how responsibilities are split between Ataccama and your organization.

This guide describes the Helm chart version 1.x. The examples use 1.0.0-saas-edge. Before you install, check Kubernetes Edge Limitations for what the Kubernetes edge doesn’t support.

What the chart installs

The chart installs three components:

Component Chart version What it does

Component	Chart version	What it does
`edge-plane-manager`	2.0.16	Receives tasks from the platform and runs each one as a Kubernetes Job in the same namespace.
`edge-interactive-jobs`	1.11.8	Handles short interactive requests, such as previews and sampling.
`dq-results-reader`	0.9.2	Returns stored data quality results from your storage container to the platform.

edge-plane-manager

2.0.16

Receives tasks from the platform and runs each one as a Kubernetes Job in the same namespace.

edge-interactive-jobs

1.11.8

Handles short interactive requests, such as previews and sampling.

dq-results-reader

0.9.2

Returns stored data quality results from your storage container to the platform.

The chart creates resources only in the namespace you install it in; it doesn’t create any cluster-wide resources. It also creates a Role that lets edge-plane-manager create and manage Jobs and read Pods and ConfigMaps in that namespace. If you set edge-plane-manager.replicas to more than one, a PodDisruptionBudget is added as well.

Prerequisites

Before you install, complete the following:

Prepare a cluster that meets the cluster requirements.
Create the Azure resources and the app registration as described in Prepare Azure Resources for Kubernetes Edge.
Allow the outbound connections listed in Kubernetes Edge Network Access Requirements.
Install Helm 3.8 or later on the machine you install from.
Make sure you have permission to create Deployments, Services, ConfigMaps, Secrets, ServiceAccounts, a Role, and a RoleBinding in the target namespace.
Size the namespace for the three components plus the data quality jobs you expect to run at the same time, as edge-plane-manager starts a Kubernetes Job for each task.

Step 1: Register the edge instance

Register the edge instance in the Ataccama Cloud Portal before you install. Registration gives you the following values, which you need for configuring the Helm values:

The edge instance name. This is also used as the client ID for the platform.
The OpenID Connect (OIDC) token endpoint of your tenant’s Ataccama identity provider (IDP) realm.
The IDP client secret for the instance.
The platform AWS account ID and region.
The Ataccama Edge gateway URL and credentials.

Step 2: Log in to the Helm registry

The chart and the container images are published to ataccama.azurecr.io. To get the registry credentials, go to your environment Settings > Edge > Container registry pull credentials in the Cloud Portal and select Generate credentials. You get a username and a password, which is a pull-only token for your environment.

The password is shown only once. If you lose it, rotate the credentials.

Use the same credentials for the Helm registry login and for the image pull Secret.

To log in before you pull the chart:

echo "$ACR_PASSWORD" | helm registry login ataccama.azurecr.io \
  --username "$ACR_USERNAME" \
  --password-stdin

To confirm that the login worked, show the chart metadata:

Show the chart metadata

helm show chart oci://ataccama.azurecr.io/saas-edge/helm/local-edge \
  --version 1.0.0-saas-edge

An authorization error means that the login was unsuccessful or that the credentials have no pull rights on the saas-edge/helm path.

helm registry login stores the credentials on disk. On a shared CI runner, log out at the end of the job with helm registry logout ataccama.azurecr.io.

Step 3: Create the image pull Secret

The registry login authenticates your machine to pull the chart. The cluster pulls the container images separately, using an image pull Secret named regcred in the target namespace. The chart doesn’t create this Secret, so create it before you install the Kubernetes edge, using the registry credentials from Ataccama:

Create the namespace and image pull Secret

kubectl create namespace <INSTANCE_NAME>
kubectl create secret docker-registry regcred \
  --namespace <INSTANCE_NAME> \
  --docker-server=ataccama.azurecr.io \
  --docker-username='<PROVIDED_BY_ATACCAMA>' \
  --docker-password='<PROVIDED_BY_ATACCAMA>'

If you mirror the images to your own registry, set global.image.registry and global.image.imagePullSecrets accordingly. The project prefix differs by registry type (saas-edge on Azure Container Registry, saas on Harbor), so change the host and the prefix together.

Step 4: Configure the Helm values

The Cloud Portal generates a values.yaml file and the Helm commands for your edge instance. To get them, select Show Helm instructions for the instance and download the values file.

The file already contains your tenant, the edge instance name, the platform region and account, the platform authentication, the image pull Secret, and the observability settings.

Complete the file before you install:

Replace the <…> placeholders.
Replace the generated customerResources section with your Azure resources, as described in Configure the Helm values.
Add the Ataccama Edge gateway settings, as described in Ataccama Edge gateway.

The following sections describe the values. For a complete example, see Example values file.

Required values

Value Description

Value	Description
`global.tenant.name`	Your tenant name. The default, `local`, is a placeholder and must be replaced.
`global.tenant.oidcUrl`	OIDC token endpoint of your tenant’s IDP realm.
`global.edge.instanceName`	Edge instance name, as registered in the Cloud Portal.
`global.agentic.auth.clientSecret.existingSecret` or `global.agentic.auth.clientSecret.value`	The IDP client secret, either as a Kubernetes Secret or inline. See Production credentials.
`global.agentic.region`, `global.agentic.platformAccountId`	The platform AWS region and account ID from the Cloud Portal. The chart has defaults for both and doesn’t check them, so always set the values shown in the Cloud Portal.
`global.agentic.gateway.*`	The Ataccama Edge gateway settings. See Ataccama Edge gateway.
`global.customerResources.*`	Your Azure storage account, container, app registration, and optionally the Key Vault key. Set `global.customerResources.azure.auth.type` to `clientSecret`, the only supported authentication type. See Configure the Helm values on the Azure prerequisites page.

global.tenant.name

Your tenant name. The default, local, is a placeholder and must be replaced.

global.tenant.oidcUrl

OIDC token endpoint of your tenant’s IDP realm.

global.edge.instanceName

Edge instance name, as registered in the Cloud Portal.

global.agentic.auth.clientSecret.existingSecret or global.agentic.auth.clientSecret.value

The IDP client secret, either as a Kubernetes Secret or inline. See Production credentials.

global.agentic.region, global.agentic.platformAccountId

The platform AWS region and account ID from the Cloud Portal. The chart has defaults for both and doesn’t check them, so always set the values shown in the Cloud Portal.

global.agentic.gateway.*

The Ataccama Edge gateway settings. See Ataccama Edge gateway.

global.customerResources.*

Your Azure storage account, container, app registration, and optionally the Key Vault key. Set global.customerResources.azure.auth.type to clientSecret, the only supported authentication type. See Configure the Helm values on the Azure prerequisites page.

Ataccama Edge gateway

All traffic from the Kubernetes edge to the platform goes through the Ataccama Edge gateway. On Azure, the gateway is the only supported path to the platform and is available exclusively through Azure Private Link. Traffic to your storage account and your data sources doesn’t go through it. For the network requirements, see Ataccama Edge gateway and platform connectivity.

Set global.agentic.gateway.enabled to true and provide the following values. You receive the gateway URL and credentials from Ataccama when you register the edge instance.

Value Required Description

Value	Required	Description
`global.agentic.gateway.enabled`	Yes	Set to `true`. All other gateway values are ignored while this is `false`.
`global.agentic.gateway.url`	Yes	Gateway URL.
`global.agentic.gateway.port`	No	Gateway port. Defaults to `443`.
`global.agentic.gateway.existingSecret`	One of the two	Kubernetes Secret that holds the gateway username and password. Recommended.
`global.agentic.gateway.username` and `global.agentic.gateway.password`	One of the two	Inline credentials. Used only when `existingSecret` is not set.
`global.agentic.gateway.existingSecretKeys.username`, `global.agentic.gateway.existingSecretKeys.password`	No	Keys in that Secret. Default to `username` and `password`.
`global.agentic.gateway.keycloakEnabled`	No	Set to `true` to send IDP sign-in traffic through the gateway as well. Defaults to `false`.

global.agentic.gateway.enabled

Yes

Set to true. All other gateway values are ignored while this is false.

global.agentic.gateway.url

Yes

Gateway URL.

global.agentic.gateway.port

Gateway port. Defaults to 443.

global.agentic.gateway.existingSecret

One of the two

Kubernetes Secret that holds the gateway username and password. Recommended.

global.agentic.gateway.username and global.agentic.gateway.password

One of the two

Inline credentials. Used only when existingSecret is not set.

global.agentic.gateway.existingSecretKeys.username, global.agentic.gateway.existingSecretKeys.password

Keys in that Secret. Default to username and password.

global.agentic.gateway.keycloakEnabled

Set to true to send IDP sign-in traffic through the gateway as well. Defaults to false.

With inline credentials, the chart creates the gateway Secret itself; with existingSecret, it uses the Secret you created.

Optional values

To encrypt data quality results with your Key Vault key, set global.customerResources.azure.keyManagement.enabled to true. Result encryption is turned off by default. See Key Vault key.

For all other values, see Configuration reference.

Example values file

The following my-values.yaml contains all required values to install the Kubernetes edge on Azure, with result encryption enabled.

The example provides the credentials inline for readability. Inline values are stored in plaintext in the Helm release and appear in helm get values.

Use them for development or demo instances only; for production, see Production credentials.

Example values file

global:
  tenant:
    name: "acme"
    oidcUrl: "https://<TENANT_HOST>.ataccama.one/realms/acme/protocol/openid-connect/token"
  edge:
    instanceName: "<INSTANCE_NAME>"
  image:
    imagePullSecrets:
      - name: regcred
  agentic:
    # These values come from the Cloud Portal.
    region: "<PROVIDED_BY_ATACCAMA>"
    platformAccountId: "<PROVIDED_BY_ATACCAMA>"
    auth:
      type: "clientSecret"
      clientSecret:
        # Dev/demo only — use existingSecret in production.
        value: "<IDP_CLIENT_SECRET>"
    gateway:
      enabled: true
      url: "https://<GATEWAY_HOST>"
      port: 443
      # Dev/demo only — use existingSecret in production.
      username: "<GATEWAY_USERNAME>"
      password: "<GATEWAY_PASSWORD>"
  customerResources:
    provider: azure
    azure:
      auth:
        type: "clientSecret"
        clientSecret:
          clientId: "11111111-2222-3333-4444-555555555555"
          tenantId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
          # Dev/demo only — use existingSecret in production.
          clientSecret: "<ENTRA_APP_SECRET>"
      resultStorage:
        storageAccountName: "<STORAGE_ACCOUNT_NAME>"
        containerName: "<CONTAINER_NAME>"
      keyManagement:
        enabled: true
        keyVaultUri: "https://<KEY_VAULT_NAME>.vault.azure.net"
        keyName: "<KEY_NAME>"

Production credentials

For production, store each credential in a Kubernetes Secret and reference it with existingSecret instead of providing it inline. The chart then creates no Secrets of its own, and no credentials are stored in the Helm release.

To create the Secrets:

Create the Kubernetes Secrets

kubectl -n <INSTANCE_NAME> create secret generic edge-keycloak-client \
  --from-literal=ATACCAMA_EDGE_KEYCLOAK_CLIENT_SECRET="$KEYCLOAK_CLIENT_SECRET"

kubectl -n <INSTANCE_NAME> create secret generic edge-customer-azure \
  --from-literal=ATACCAMA_EDGE_JOB_CUSTOMER_AZURE_CLIENT_SECRET="$AZURE_CLIENT_SECRET"

kubectl -n <INSTANCE_NAME> create secret generic edge-platform-gateway \
  --from-literal=username="$GATEWAY_USERNAME" \
  --from-literal=password="$GATEWAY_PASSWORD"

Reference them in the values file:

Values file that references the Secrets

global:
  agentic:
    auth:
      clientSecret:
        existingSecret: "edge-keycloak-client"
    gateway:
      existingSecret: "edge-platform-gateway"
  customerResources:
    azure:
      auth:
        clientSecret:
          clientId: "11111111-2222-3333-4444-555555555555"
          tenantId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
          existingSecret: "edge-customer-azure"

The client ID and tenant ID aren’t secrets and stay in the values file. The Secret keys in the example are the defaults. To use different keys, set them under existingSecretKey for the IDP client secret, and under existingSecretKeys for the Azure and gateway credentials. When existingSecret is set, an inline value for the same credential is ignored.

Using Secrets also simplifies credential rotation. If the app registration password is rotated, an inline value becomes invalid and must be updated with helm upgrade. With existingSecret, update the Secret, then restart the edge-plane-manager, edge-interactive-jobs, and dq-results-reader Deployments so they read the new value. Job pods started after the update use the new value automatically.

Step 5: Install the Kubernetes edge

Validate your values by rendering the chart locally:

helm template local-edge oci://ataccama.azurecr.io/saas-edge/helm/local-edge \
  --version 1.0.0-saas-edge \
  -f my-values.yaml

If a required value is missing, the render fails and lists all missing values. For example, a values file that sets only provider: azure produces:

Error: execution error at (local-edge/templates/validate-values.yaml:108:4): local-edge values are invalid:
- global.tenant.oidcUrl is required
- global.agentic.auth.clientSecret: set existingSecret or value when auth.type is clientSecret
- global.customerResources.azure.resultStorage.storageAccountName is required when customerResources.provider is azure
- global.customerResources.azure.resultStorage.containerName is required when customerResources.provider is azure
- global.customerResources.azure.auth.clientSecret.clientId is required when azure.auth.type is clientSecret
- global.customerResources.azure.auth.clientSecret.tenantId is required when azure.auth.type is clientSecret
- global.customerResources.azure.auth.clientSecret: set existingSecret or clientSecret when azure.auth.type is clientSecret

Install the chart:

helm upgrade --install local-edge oci://ataccama.azurecr.io/saas-edge/helm/local-edge \
  --version 1.0.0-saas-edge \
  --namespace <INSTANCE_NAME> --create-namespace \
  -f my-values.yaml

Wait for all three Deployments to become available:

kubectl -n <INSTANCE_NAME> rollout status deployment/edge-plane-manager --timeout=180s
kubectl -n <INSTANCE_NAME> rollout status deployment/edge-interactive-jobs --timeout=180s
kubectl -n <INSTANCE_NAME> rollout status deployment/dq-results-reader --timeout=180s

In the Cloud Portal, confirm that the edge instance shows as connected.

Step 6: Configure data sources to use the edge

When creating or editing your data source connection, select the edge instance you want to use. All edge instances available for your environment appear in this list.

Then select a Compliance mode for the connection. It controls which processing results can leave your edge environment:

Strict (no data leaves Edge): No sensitive data leaves your edge environment.
Normal (DQ results visible): DQ results, including invalid record samples and full profiling results, are available in Ataccama ONE.
Allow exports: The same as Normal (DQ results visible), and data processed on this connection’s edge can also be loaded to Reference data.

For details, see Compliance mode.

Test and save the connection. Then browse and import metadata for a schema, table, or file of your choosing. As a result, a new catalog item appears in your Catalog.

For detailed instructions, see Sources and Import Metadata.

If any step results in an error, contact Ataccama Support.

Upgrade the Kubernetes edge

New releases are published weekly, and each version is supported for 90 days. Upgrade within that window, and upgrade one version at a time.

To upgrade to a new chart version, run helm upgrade with the new version and the same values file:

Upgrade the Kubernetes edge

helm upgrade local-edge oci://ataccama.azurecr.io/saas-edge/helm/local-edge \
  --version <NEW_VERSION> \
  --namespace <INSTANCE_NAME> \
  -f my-values.yaml

Helm doesn’t carry values over from the previous release unless you pass --reuse-values. Any value you omit, including credentials set on the command line, is dropped. With existingSecret, there is nothing to re-supply, as the release holds no credentials.

Uninstall the Kubernetes edge

To uninstall the Kubernetes edge, remove the Helm release. This removes everything the chart created. It doesn’t remove the namespace, the regcred Secret, Secrets you created yourself, or anything in your storage container.

Uninstall the Kubernetes edge

helm uninstall local-edge --namespace <INSTANCE_NAME>

Configuration reference

This guide describes only the values required to install the Kubernetes edge. For the full list of configuration options, see the values.yaml file included in the chart.

To display the file without unpacking the chart, run:

Display the chart values

helm show values oci://ataccama.azurecr.io/saas-edge/helm/local-edge \
  --version 1.0.0-saas-edge

To download and unpack the chart, including its templates, run:

Download and unpack the chart

helm pull oci://ataccama.azurecr.io/saas-edge/helm/local-edge \
  --version 1.0.0-saas-edge --untar

Values can be set in a file (-f) or on the command line (--set). Use --set-string for values that could be misread as a number or Boolean, and for all secrets.

Observability

The values file generated in the Cloud Portal includes a global.agentic.observability section that sends logs and telemetry to Ataccama observability through the Ataccama Edge gateway. Keep it as generated. The endpoint is for Ataccama use only; you can’t use it to send telemetry to your own collector.

To change log levels of the plane manager and edge-interactive-jobs, set edge-plane-manager.logging.* and edge-interactive-jobs.logLevel.

Troubleshooting

The render fails with "local-edge values are invalid"

Cause: One or more required values are missing; the error message lists which ones.

Solution: Provide the missing values and render again. See Required values.

Pods stay in ImagePullBackOff

Cause: The regcred Secret is missing from the namespace, has the wrong registry host, or holds expired credentials.

Solution: Create or update the Secret as described in Step 3: Create the image pull Secret.

edge-plane-manager starts but no jobs run

Cause: The edge can’t reach the platform, or global.edge.instanceName doesn’t match the name registered in the Cloud Portal.

Solution: Check that the pods can reach the Ataccama Edge gateway, and that global.edge.instanceName matches the registered name.

The edge fails to authenticate to the platform

Cause: global.tenant.oidcUrl or the IDP client secret is wrong. The client ID is global.edge.instanceName, so a mismatch there also shows up as an authentication failure.

Solution: Check the OIDC URL, the client secret, and the instance name against the values from the Cloud Portal.

A credential change had no effect

Cause: When existingSecret is set, inline values and --set-string for that credential are ignored.

Solution: Update the Secret instead, or remove existingSecret.

Gateway requests return HTTP 407

Cause: The Ataccama Edge gateway credentials are wrong or missing, or global.agentic.gateway.url points to the wrong endpoint. Neither is validated at install time.

Solution: Check the values in Ataccama Edge gateway.

Collect state after a failure

Collect pod state and logs

kubectl -n <INSTANCE_NAME> get pods -o wide
kubectl -n <INSTANCE_NAME> describe pods
kubectl -n <INSTANCE_NAME> logs deployment/edge-plane-manager

Was this page useful?