Set up Secrets Operator

This page walks you through installing Aembit Secrets OperatorAembit Secrets Operator: Aembit Secrets Operator is a Kubernetes operator that authenticates to the Aembit platform and synchronizes credentials into Kubernetes Secrets for applications to consume directly.Learn more in your Kubernetes cluster and configuring it to retrieve credentials from the Aembit platform.

Secrets Operator supports two authentication paths to the Aembit platform:

• OIDC symmetric key (HS256): Secrets Operator signs tokens with a shared secret you generate and configure. Choose this when you need custom claims (for example, a store number), non-Kubernetes identity, or want to keep an existing prototype configuration. The following steps use this path.
• Kubernetes Service Account: Secrets Operator authenticates using its in-cluster ServiceAccount token, validated by your cluster’s OIDC endpoint. No signing key required. Choose this for Kubernetes-native identity and tighter match rules (namespace, pod name, ServiceAccount name). See Kubernetes Service Account authentication.

Prerequisites

Before you begin, ensure you have:

• A Kubernetes cluster (verified on Amazon EKS and K3s)
• kubectl configured for your target cluster
• Helm v3.x installed

If you plan to use CrowdStrike Access ConditionsAccess Condition: Access Conditions add dynamic, context-aware constraints to authorization by evaluating circumstances like time, location, or security posture to determine whether to grant access.Learn more, you also need:

• CrowdStrike Falcon agent installed on cluster nodes
• CrowdStrike Agent ID written to /etc/aembit/crowdstrike-aid on each node

Create the OIDC signing key

Secrets Operator authenticates to Aembit using OIDCOpenID Connect (OIDC): An identity layer built on top of OAuth 2.0 that lets applications verify the identity of a user or workload and obtain basic profile information using JSON Web Tokens (JWTs).Learn more(opens in new tab) tokens signed with a symmetric key. Generate a cryptographically random key and store it as a Kubernetes Secret. You need the base64-encoded value from this Secret when you configure the Trust ProviderTrust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more in your Aembit tenant.

1. Generate the key and create the Secret:

   # Generate a 32-byte random key and create the Secret
   openssl rand 32 | kubectl create secret generic aembit-oidc-signing-key \
     --from-file=key=/dev/stdin \
     --namespace <your-namespace>

2. Retrieve the base64-encoded key value for use in your Trust Provider:

   kubectl get secret aembit-oidc-signing-key \
     --namespace <your-namespace> \
     -o jsonpath='{.data.key}'

   Copy this value—you paste it into the Trust Provider’s symmetric key field in the next section.

Avoid double base64 encoding

Kubernetes automatically base64-encodes Secret data. When you configure the Trust Provider, paste the base64-encoded value from the preceding command directly into the symmetric key field. Don’t base64-encode the value yourself before pasting—doing so results in a double-encoded key that causes authentication failures.

Key requirements

The signing key must be at least 32 bytes of cryptographically random data. Secrets Operator rejects keys shorter than 32 bytes (per RFC 7518 §3.2) when generating tokens.

Note

If you change the OIDC signing key Secret after Secrets Operator is running, you must restart the Secrets Operator pod for Secrets Operator to pick up the new key.

Create the claims ConfigMap

Create a ConfigMap that defines the OIDC claims included in Secrets Operator’s identity tokens. The iss (issuer) and sub (subject) claims control how the Trust Provider identifies Secrets Operator. You can also add claims for per-cluster access policies.

kubectl create configmap aembit-oidc-claims \
  --namespace <your-namespace> \
  --from-literal=iss=https://aembit-secrets-operator.example.com \
  --from-literal=sub=aembit-secrets-operator

Why create this ConfigMap

Without a claims ConfigMap, Secrets Operator infers a default iss claim that’s specific to the cluster and difficult to obtain. To find it, you would need to install the Helm chart and check Secrets Operator logs. Creating the ConfigMap upfront gives you explicit control over the iss and sub values, which makes configuring Trust Provider match rules straightforward.

You reference this ConfigMap in the AembitEdgeApiClient custom resource when you create custom resources.

Configure your Aembit tenant

Set up the required Aembit resources to define the access policy for Secrets Operator. Secrets Operator authenticates using OIDC tokens signed with a symmetric key, so the Trust Provider and Client WorkloadClient Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more both use the OIDC ID Token type.

1. Log in to your Aembit tenant and create a Client Workload:

   • Set the identification method to OIDC ID Token.
   • Configure the subject match value to match the sub value you set in the claims ConfigMap (for example, aembit-secrets-operator).

2. Create a Trust Provider:

   • Set the type to OIDC ID Token.
   • Select Symmetric Key as the attestation method.
   • Paste the base64-encoded key value you copied in Create the OIDC signing key.
   • Configure match rules for iss (issuer) and sub (subject) to match the values you set in the claims ConfigMap.
   • Note the Edge SDK Client ID—you need this for the clientId field in the AembitEdgeApiClient Custom Resource Definition (CRD).

3. Create a Server WorkloadServer Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more pointing to your HashiCorp Vault instance:

   • Configure the host and port to match the values you plan to set in the AembitSecretRefreshSchedule CRD (server.host and server.port).

4. Create a Credential ProviderCredential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more:

   • Select Vault Client Token as the credential type.
   • Configure the JWT subject, custom claims, and Vault authentication details.
   • See Configure a HashiCorp Vault Client Token Credential Provider for detailed instructions.

5. (Optional) Create an Access Condition for CrowdStrike device posture validation. If enabled, Secrets Operator passes host attestation data (hostname, serial number, CrowdStrike Agent ID) with every authentication request. See Prepare host attestations to configure the host attestation file.

6. Create an Access PolicyAccess Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more linking the Client Workload, Trust Provider, Server Workload, Credential Provider, and any Access Conditions.

7. Note the following values from your tenant configuration. You need these for the CRD configuration:

   Value	Where to find it	Used in
   Tenant ID	Tenant settings	AembitEdgeApiClient spec.tenantId
   Edge SDK Client ID	Trust Provider details page	AembitEdgeApiClient spec.clientId
   Resource Set ID (if applicable)	Resource Set settings	AembitEdgeApiClient spec.resourceSetId
   Server Workload host and port	Server Workload configuration	AembitSecretRefreshSchedule spec.server

Prepare host attestations (optional)

If your Access Policy includes Access Conditions that validate device posture (for example, CrowdStrike device identity), prepare a host attestations file on each cluster node before deploying Secrets Operator.

Secrets Operator reads host attestation data from a file mounted into the pod via a hostPath volume. The file must be available at the configured path (default: /run/aembit/host_attestations.json) on each node.

The file must contain a JSON object that satisfies the host field of the Edge API authentication schema. For example:

/run/aembit/host_attestations.json

{
  "hostname": "node-01.example.com",
  "domainName": "example.com",
  "systemSerialNumber": "ABC123DEF456",
  "sensors": {
    "crowdStrike": {
      "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

For more details on configuring host attestations, see the host attestations reference.

Install the Helm chart

Use a dedicated namespace

Install Secrets Operator in its own namespace. The Helm chart creates a ServiceAccount with access to all Secrets in the namespace, and the OIDC signing key is readable by any ServiceAccount in the same namespace. A dedicated namespace limits the blast radius of these permissions.

If you install the chart more than once in a cluster, install each instance into its own namespace. The chart creates one ClusterRole and ClusterRoleBinding per installation; these names include the install namespace, so the same Helm release name works across multiple namespaces without conflicts.

For details, see Security model.

1. Add the Aembit Helm repository:

   helm repo add aembit https://helm.aembit.io
   helm repo update

   Repo name conflict

   If you see this error:

   Error: repository name (aembit) already exists, please specify a different name

   You already have a local Helm repo registered under that name. Run helm repo list to see your existing repos and choose a different alias for this command.

2. (Optional) Create a values.yaml file to override default chart values. For the complete list of configurable values, see the Helm chart values reference.

3. Install Secrets Operator:

   helm install aembit-secrets-operator aembit/aembit-secrets-operator \
     --namespace aembit-system \
     --create-namespace

   If you created a values.yaml, add --values values.yaml to the command.

4. Verify the Secrets Operator pod is running:

   kubectl get pods --namespace aembit-system

   Expected output:

   NAME                                    READY   STATUS    RESTARTS   AGE
   aembit-secrets-operator-<id>            1/1     Running   0          30s

Create custom resources

Create the custom resources that tell Secrets Operator what credentials to manage.

Installation order

Installing the Helm chart and creating custom resources are independent operations—you can do either first. This guide recommends installing the Helm chart first because it registers the Custom Resource Definitions (CRDs) that Kubernetes needs to accept the custom resources below.

1. Save the following manifest as aembit-connection.yaml, replacing the placeholder values with the tenant ID and Edge SDK Client ID from your Aembit tenant:

   aembit-connection.yaml

   apiVersion: aembit.io/v1
   kind: AembitEdgeApiClient
   metadata:
     name: aembit-connection
     namespace: aembit-system
   spec:
     tenantId: "<your-tenant-id>"
     clientId: "<your-edge-sdk-client-id>"
     # resourceSetId: "<your-resource-set-id>"  # Optional
     attestations:
       oidc:
         source: generated
         signingSecretRef:
           name: aembit-oidc-signing-key
           secretField: key
         claimsConfigMapRef:
           name: aembit-oidc-claims

2. Apply the manifest to create the AembitEdgeApiClient resource:

   kubectl apply -f aembit-connection.yaml

3. Save the following manifest as vault-token-schedule.yaml, replacing the server.host and server.port values with your Vault instance details. Create one AembitSecretRefreshSchedule for each credential you need managed:

   vault-token-schedule.yaml

   apiVersion: aembit.io/v1
   kind: AembitSecretRefreshSchedule
   metadata:
     name: vault-token-schedule
     namespace: aembit-system
   spec:
     aembitEdgeApiClientRef:
       name: aembit-connection
     targetSecretName: vault-token
     server:
       host: vault.example.com
       port: 8200
     # refreshInterval: "4h"  # Optional: omit to use the credential's natural lifetime

4. Apply the manifest to create the schedule:

   kubectl apply -f vault-token-schedule.yaml

Verify the installation

Confirm Secrets Operator is managing credentials successfully.

1. Check the status of your custom resources:

   kubectl get aembitedgeapiclient --namespace aembit-system
   kubectl get aembitsecretrefreshschedule --namespace aembit-system

2. Inspect the credential schedule status for details:

   kubectl describe aembitsecretrefreshschedule vault-token-schedule --namespace aembit-system

   Look for phase: Ready and a recent lastSyncTime indicating successful credential retrieval. See the status fields reference for details.

3. Verify that the target Secret exists:

   kubectl get secret vault-token --namespace aembit-system

   The Secret should exist and contain the credential data.

Kubernetes Service Account authentication

Kubernetes Service Account authentication is an alternative to the OIDC symmetric key path above. Secrets Operator authenticates using its in-cluster ServiceAccount token — no signing key or claims ConfigMap required.

Skip the Create the OIDC signing key and Create the claims ConfigMap sections. All other steps (install the Helm chart, create custom resources, verify) are the same.

Configure your Aembit tenant for Kubernetes Service Account authentication

In the Configure your Aembit tenant steps, make these changes:

1. Create a Client Workload:

   • Set the identification method to Kubernetes Service Account.
   • Configure match rules to identify the Secrets Operator pod (for example, namespace and ServiceAccount name).

2. Create a Trust Provider:

   • Set the type to Kubernetes Service Account.
   • Provide your cluster’s OIDC issuer URL. See Kubernetes Service Account Trust Provider for instructions by cluster type (EKS and K3s).
   • Configure match rules (namespace, pod name, ServiceAccount name, or subject).
   • Note the Edge SDK Client ID — you need this for the clientId field.

3. Complete the remaining tenant steps (Server Workload, Credential Provider, Access Policy) the same way.

Create the AembitEdgeApiClient for Kubernetes Service Account authentication

Use kubernetesServiceAccount: {} instead of oidc: in the attestations field:

aembit-connection.yaml

apiVersion: aembit.io/v1
kind: AembitEdgeApiClient
metadata:
  name: aembit-connection
  namespace: aembit-system
spec:
  tenantId: "<your-tenant-id>"
  clientId: "<your-edge-sdk-client-id>"
  attestations:
    kubernetesServiceAccount: {}          # uses default SA token path
    # kubernetesServiceAccount:           # or use a custom projected-volume path:
    #   tokenPath: /var/run/secrets/custom/token

Apply the manifest and then create the AembitSecretRefreshSchedule as described in Create custom resources. The credential retrieval flow is identical regardless of auth path.

Next steps

• Configuration Reference: CRD specifications, environment variables, and host attestations.
• Helm chart values: All configurable Helm chart values.
• Vault Client Token Credential Provider: Configure the Aembit Credential Provider for HashiCorp Vault.