Skip to main content
Version: Next 🚧

How to: Deploy a CompositionDefinition

Concepts: CompositionDefinition · Chart Requirements · Lifecycle Workflow

A CompositionDefinition registers a Helm chart as a versioned Kubernetes API. This guide walks through deploying the GitHub Scaffolding Lifecycle chart from the Krateo Marketplace, which is used throughout these how-to guides.

Prerequisites​

1. Create a namespace​

kubectl create namespace cheatsheet-system

2. Deploy the CompositionDefinition​

cat <<EOF | kubectl apply -f -
apiVersion: core.krateo.io/v1alpha1
kind: CompositionDefinition
metadata:
  name: lifecycleapp-cd-v1
  namespace: cheatsheet-system
spec:
  chart:
    repo: github-scaffolding-lifecycle
    url: https://marketplace.krateo.io
    version: 0.0.1
EOF

3. Wait for it to become ready​

kubectl wait compositiondefinition lifecycleapp-cd-v1 \
  --for condition=Ready=True \
  --namespace cheatsheet-system \
  --timeout=600s

What happens: The Core Provider downloads the chart from the Krateo Marketplace, validates values.schema.json, generates the CRD, creates RBAC resources, and deploys the CDC. Once all steps complete, the condition flips to Ready=True.

Verify the CompositionDefinition​

kubectl get compositiondefinition -n cheatsheet-system

You should see lifecycleapp-cd-v1 with Ready=True.

Advanced: Alternative Chart Sources​

OCI Registry​

To deploy from an OCI registry instead of a Helm repository:

cat <<EOF | kubectl apply -f -
apiVersion: core.krateo.io/v1alpha1
kind: CompositionDefinition
metadata:
  name: lifecycleapp-cd-v1
  namespace: cheatsheet-system
spec:
  chart:
    url: oci://registry-1.docker.io/yourusername/my-chart
    version: "0.1.0"
EOF

Examples: OCI with repo field · OCI without repo field

TGZ Archive (direct URL)​

To deploy from a direct TGZ archive URL:

cat <<EOF | kubectl apply -f -
apiVersion: core.krateo.io/v1alpha1
kind: CompositionDefinition
metadata:
  name: lifecycleapp-cd-v1
  namespace: cheatsheet-system
spec:
  chart:
    url: https://example.com/charts/my-chart-0.1.0.tgz
    version: "0.1.0"
EOF

Example: TGZ archive example

Advanced: Authentication for Private Registries​

If your chart source is private, add a credentials block to spec.chart.

OCI Registry​

Create the secret first:

kubectl create secret generic my-registry-secret \
  --from-literal=token=YOUR_TOKEN \
  -n cheatsheet-system

Then add credentials to the CompositionDefinition:

spec:
  chart:
    url: oci://registry-1.docker.io/yourusername/my-chart
    version: "0.1.0"
    credentials:
      username: yourusername
      passwordRef:
        key: token
        name: my-registry-secret
        namespace: cheatsheet-system

GCP Artifact Registry​

Create the secret from your service account key JSON file (the service account needs Artifact Registry Reader permissions):

kubectl create secret generic gcp-sa-secret -n cheatsheet-system \
  --from-file=secret-access-credentials=/path/to/krateoregistry-key.json

Then configure the CompositionDefinition:

spec:
  chart:
    url: oci://europe-west12-docker.pkg.dev/myproject/myrepo/my-chart
    version: "0.0.1"
    credentials:
      username: json_key          # required literal value for GCP
      passwordRef:
        key: secret-access-credentials
        name: gcp-sa-secret
        namespace: cheatsheet-system

The username must be json_key for GCP Artifact Registry. See the GCP documentation.

Helm Repository​

Create the secret:

kubectl create secret generic helm-repo-secret \
  --from-literal=token=YOUR_TOKEN \
  -n cheatsheet-system

Then add credentials:

spec:
  chart:
    repo: my-chart
    url: https://charts.example.com
    version: "0.3.0"
    credentials:
      username: yourusername
      passwordRef:
        key: token
        name: helm-repo-secret
        namespace: cheatsheet-system

Next steps​