Skip to main content
Version: v0.9.x

Component Workflow Secrets

ComponentWorkflows often need access to secrets for authentication during the build process. This guide explains how to provide secrets to the Build Plane for common scenarios like cloning from private repositories and pushing to private registries.

Overview​

Build workflows require credentials for:

  • Git authentication - Cloning source code from private repositories (GitHub, GitLab, Bitbucket)
  • Registry authentication - Pushing container images to private registries (Docker Hub, GCR, ECR, Azure ACR)
  • External services - Accessing APIs or services during the build process

OpenChoreo supports two approaches for providing secrets to the Build Plane:

  1. External Secrets Operator (Recommended for GitOps) - Automatically sync secrets from external secret managers
  2. Manual Secret Creation - Create Kubernetes secrets directly in the Build Plane

Secret Management Approaches​

Use the resources field in ComponentWorkflow to define ExternalSecret resources that automatically sync secrets from external secret managers like AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, and more.

Benefits:

  • Secrets are automatically synced
  • No manual secret management required
  • Ideal for GitOps workflows where all configuration is version-controlled
  • Secrets never appear in Git repositories

Example:

apiVersion: openchoreo.dev/v1alpha1
kind: ComponentWorkflow
metadata:
  name: my-workflow
spec:
  # ... schema and runTemplate ...

  resources:
    - id: registry-credentials
      template:
        apiVersion: external-secrets.io/v1
        kind: ExternalSecret
        metadata:
          name: registry-push-secret
          namespace: openchoreo-ci-${metadata.orgName}
        spec:
          refreshInterval: 15s
          secretStoreRef:
            name: default
            kind: ClusterSecretStore
          target:
            name: registry-push-secret
            creationPolicy: Owner
          data:
            - secretKey: dockerconfig
              remoteRef:
                key: my-secret-key
                property: dockerconfigjson

The ExternalSecret resource is created in the build execution namespace (e.g., openchoreo-ci-default) and automatically syncs credentials from your configured secret store.

Option 2: Manual Secret Creation​

Create Kubernetes secrets directly in the Build Plane's execution namespace. This is simpler for development and testing environments.

Benefits:

  • Simple setup for development and testing
  • No additional operators required
  • Direct control over secret lifecycle

Secrets are created in the build execution namespace, which follows the pattern openchoreo-ci-{organization-name}.

Private Git Repositories​

When building from private repositories, the clone step needs authentication credentials.

External Secrets Setup​

  1. Store your Git access token in your secrets manager

  2. Add the ExternalSecret resource to your ComponentWorkflow:

apiVersion: openchoreo.dev/v1alpha1
kind: ComponentWorkflow
metadata:
  name: my-workflow
spec:
  resources:
    - id: git-credentials
      template:
        apiVersion: external-secrets.io/v1
        kind: ExternalSecret
        metadata:
          name: git-clone-secret
          namespace: openchoreo-ci-${metadata.orgName}
        spec:
          refreshInterval: 15s
          secretStoreRef:
            name: default
            kind: ClusterSecretStore
          target:
            name: git-clone-secret
            creationPolicy: Owner
          data:
            - secretKey: clone-secret
              remoteRef:
                key: github-pat
                property: token

Manual Setup​

  1. Generate a personal access token from your Git provider.

  2. Create the secret:

kubectl create secret generic git-clone-secret \
  --from-literal=clone-secret=<your-personal-access-token> \
  -n openchoreo-ci-default

Or apply a YAML manifest:

apiVersion: v1
kind: Secret
metadata:
  name: git-clone-secret
  namespace: openchoreo-ci-default
type: Opaque
stringData:
  clone-secret: '<your-personal-access-token>'

Private Container Registries​

When pushing built images to private registries, the push step needs registry credentials.

External Secrets Setup​

  1. Store your Docker config JSON in your secrets manager

  2. Add the ExternalSecret resource to your ComponentWorkflow:

apiVersion: openchoreo.dev/v1alpha1
kind: ComponentWorkflow
metadata:
  name: my-workflow
spec:
  resources:
    - id: registry-credentials
      template:
        apiVersion: external-secrets.io/v1
        kind: ExternalSecret
        metadata:
          name: registry-push-secret
          namespace: openchoreo-ci-${metadata.orgName}
        spec:
          refreshInterval: 15s
          secretStoreRef:
            name: default
            kind: ClusterSecretStore
          target:
            name: registry-push-secret
            creationPolicy: Owner
          data:
            - secretKey: .dockerconfigjson
              remoteRef:
                key: registry-credentials
                property: dockerconfigjson

Manual Setup​

  1. Generate credentials for your registry.

  2. Create the docker-registry secret:

kubectl create secret docker-registry registry-push-secret \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=your-username \
  --docker-password=your-password \
  -n openchoreo-ci-default

For multiple registries or custom docker config:

# Create docker-config.json
cat > docker-config.json <<EOF
{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "$(echo -n 'username:password' | base64)"
    },
    "gcr.io": {
      "auth": "$(cat gcr-key.json | base64)"
    }
  }
}
EOF

# Create secret from file
kubectl create secret generic registry-push-secret \
  --from-file=.dockerconfigjson=docker-config.json \
  --type=kubernetes.io/dockerconfigjson \
  -n openchoreo-ci-default

Runtime Image Pull Credentials​

Pushing images to a registry (Build Plane) and pulling images at runtime (Data Plane) require separate credential configuration since they operate in different planes.

Adding Pull Secrets to ComponentType​

To pull images from private registries, you need to add imagePullSecrets to the Deployment template in your ComponentType's resources field.

Option 1: Using External Secrets (Recommended)

For automatic secret creation, create an ExternalSecret resource in your ComponentType:

apiVersion: openchoreo.dev/v1alpha1
kind: ComponentType
metadata:
  name: my-service-type
spec:
  resources:
    # ExternalSecret to sync pull credentials
    - id: registry-pull-secret
      template:
        apiVersion: external-secrets.io/v1
        kind: ExternalSecret
        metadata:
          name: registry-pull-secret
          namespace: ${metadata.namespace}
        spec:
          refreshInterval: 15s
          secretStoreRef:
            name: ${dataplane.secretStore}
            kind: ClusterSecretStore
          target:
            name: registry-pull-secret
            creationPolicy: Owner
            template:
              type: kubernetes.io/dockerconfigjson
          data:
            - secretKey: .dockerconfigjson
              remoteRef:
                key: registry-credentials
                property: dockerconfigjson

    # Deployment that uses the pull secret
    - id: deployment
      template:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: ${metadata.name}
          namespace: ${metadata.namespace}
        spec:
          template:
            spec:
              imagePullSecrets:
                - name: registry-pull-secret
              containers:
                - name: main
                  image: ${workload.containers[parameters.containerName].image}
                  # ... container configuration

Option 2: Manual Secret Creation

  1. Create the docker-registry secret in the Data Plane namespace:
kubectl create secret docker-registry registry-pull-secret \
  --docker-server=<registry-url> \
  --docker-username=<username> \
  --docker-password=<password> \
  -n openchoreo-data-plane
  1. Add the imagePullSecrets field to your ComponentType's Deployment template:
apiVersion: openchoreo.dev/v1alpha1
kind: ComponentType
metadata:
  name: my-service-type
spec:
  resources:
    - id: deployment
      template:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: ${metadata.name}
          namespace: ${metadata.namespace}
        spec:
          template:
            spec:
              # Add imagePullSecrets here
              imagePullSecrets:
                - name: registry-pull-secret
              containers:
                - name: main
                  image: ${workload.containers[parameters.containerName].image}
                  # ... container configuration

Next Steps​