Skip to main content

Chainloop Helm Chart

Chainloop is an open-source software supply chain control plane, a single source of truth for artifacts plus a declarative attestation crafting process.

Introduction

This chart bootstraps a Chainloop deployment on a Kubernetes cluster using the Helm package manager.

Prerequisites

  • Kubernetes 1.19+
  • Helm 3.2.0+
  • PV provisioner support in the underlying infrastructure (If built-in PostgreSQL is enabled)

Compatibility with the following Ingress Controllers has been verified, other controllers might or might not work.

TL;DR

Deploy Chainloop in development mode by running

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    --set development=true \
    --set controlplane.auth.oidc.url=[OIDC URL] \
    --set controlplane.auth.oidc.clientID=[clientID] \
    --set controlplane.auth.oidc.clientSecret=[clientSecret]

CAUTION: Do not use this mode in production, for that, use the standard mode instead.

Installing the Chart

This chart comes in two flavors, standard and development.

Standard (default)

The default deployment mode relies on external dependencies to be available in advance.

The Helm Chart in this mode includes

During installation, you'll need to provide

Instructions on how to create the ECDSA keypair can be found here.

Installation Examples

NOTE: We do not recommend passing nor storing sensitive data in plain text. For production, please consider having your overrides encrypted with tools such as Sops, Helm Secrets or Sealed Secrets.

Deploy Chainloop configured to talk to the bundled PostgreSQL an external OIDC IDp and a Vault instance.

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    # Open ID Connect (OIDC)
    --set controlplane.auth.oidc.url=[OIDC URL] \
    --set controlplane.auth.oidc.clientID=[clientID] \
    --set controlplane.auth.oidc.clientSecret=[clientSecret] \
    # Secrets backend
    --set secretsBackend.vault.address="https://[vault address]:8200" \
    --set secretsBackend.vault.token=[token] \
    # Server Auth KeyPair
    --set casJWTPrivateKey="$(cat private.ec.key)" \
    --set casJWTPublicKey="$(cat public.pem)"

Deploy using AWS Secrets Manager instead of Vault

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    # Open ID Connect (OIDC)
    # ...
    # Secrets backend
    --set secretsBackend.backend=awsSecretManager \
    --set secretsBackend.awsSecretManager.accessKey=[AWS ACCESS KEY ID] \
    --set secretsBackend.awsSecretManager.secretKey=[AWS SECRET KEY] \
    --set secretsBackend.awsSecretManager.region=[AWS region]\
    # Server Auth KeyPair
    # ...

or using GCP Secret Manager

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    # Open ID Connect (OIDC)
    # ...
    # Secrets backend
    --set secretsBackend.backend=gcpSecretManager \
    --set secretsBackend.gcpSecretManager.projectId=[GCP Project ID] \
    --set secretsBackend.gcpSecretManager.serviceAccountKey=[GCP Auth KEY] \
    # Server Auth KeyPair
    # ...

or Azure KeyVault

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    # Open ID Connect (OIDC)
    # ...
    # Secrets backend
    --set secretsBackend.backend=azureKeyVault \
    --set secretsBackend.azureKeyVault.tenantID=[AD tenant ID] \
    --set secretsBackend.azureKeyVault.clientID=[Service Principal ID] \
    --set secretsBackend.azureKeyVault.clientSecret=[Service Principal secret] \
    --set secretsBackend.azureKeyVault.vaultURI=[Azure KeyVault URI]
    # Server Auth KeyPair
    # ...

Connect to an external PostgreSQL database instead

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    # Open ID Connect (OIDC)
    # ...
    # Secrets backend
    # ...
    # Server Auth KeyPair
    # ...
    # External DB setup
    --set postgresql.enabled=false \
    --set controlplane.externalDatabase.host=[DB_HOST] \
    --set controlplane.externalDatabase.user=[DB_USER] \
    --set controlplane.externalDatabase.password=[DB_PASSWORD] \
    --set controlplane.externalDatabase.database=[DB_NAME]

Development

To provide an easy way to give Chainloop a try, this Helm Chart has an opt-in development mode that can be enabled with the flag development=true

IMPORTANT: DO NOT USE THIS MODE IN PRODUCTION

The Helm Chart in this mode includes

  • Chainloop Controlplane
  • Chainloop Artifact proxy
  • A PostgreSQL dependency enabled by default
  • A pre-configured Hashicorp Vault instance running in development mode (unsealed, in-memory, insecure)

CAUTION: Do not use this mode in production, for that, use the standard mode instead.

During installation, you'll need to provide

Installation Examples

Deploy by leveraging built-in Vault and PostgreSQL instances

helm install [RELEASE_NAME] oci://ghcr.io/chainloop-dev/charts/chainloop \
    --set development=true \
    --set controlplane.auth.oidc.url=[OIDC URL] \
    --set controlplane.auth.oidc.clientID=[clientID] \
    --set controlplane.auth.oidc.clientSecret=[clientSecret]

How to guides

CAS upload speeds are slow, what can I do?

Chainloop uses gRPC streaming to perform artifact uploads. This method is susceptible to being very slow on high latency scenarios. #375

To improve upload speeds, you need to increase http2 flow control buffer. This can be done in NGINX by setting the following annotation in the ingress resource.

# Improve upload speed by adding client buffering used by http2 control-flows
nginx.ingress.kubernetes.io/client-body-buffer-size: "3M"

Note: For other reverse proxies, you'll need to find the equivalent configuration.

Generate a ECDSA key-pair

An ECDSA key-pair is required to perform authentication between the control-plane and the Artifact CAS

You can generate both the private and public keys by running

# Private Key (private.ec.key)
openssl ecparam -name secp521r1 -genkey -noout -out private.ec.key
# Public Key (public.pem)
openssl ec -in private.ec.key -pubout -out public.pem

Then, you can either provide it in a custom values.yaml file override

casJWTPrivateKey: |-
  -----BEGIN EC PRIVATE KEY-----
  REDACTED
  -----END EC PRIVATE KEY-----
casJWTPublicKey: |
  -----BEGIN PUBLIC KEY-----
  REDACTED
  -----END PUBLIC KEY-----

or as shown before, provide them as imperative inputs during Helm Install/Upgrade --set casJWTPrivateKey="$(cat private.ec.key)"--set casJWTPublicKey="$(cat public.pem)"

Enable a custom domain with TLS

Chainloop uses three endpoints so we'll need to enable the ingress resource for each one of them.

See below an example of a values.yaml override

controlplane:
  ingress:
    enabled: true
    hostname: cp.chainloop.dev

  ingressAPI:
    enabled: true
    hostname: api.cp.chainloop.dev

cas:
  ingressAPI:
  enabled: true
  hostname: api.cas.chainloop.dev

A complete setup that uses

would look like

controlplane:
  ingress:
    enabled: true
    tls: true
    ingressClassName: nginx
    hostname: cp.chainloop.dev
    annotations:
      # This depends on your configured issuer
      cert-manager.io/cluster-issuer: "letsencrypt-prod"

  ingressAPI:
    enabled: true
    tls: true
    ingressClassName: nginx
    hostname: api.cp.chainloop.dev
    annotations:
      nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
      cert-manager.io/cluster-issuer: "letsencrypt-prod"

cas:
  ingressAPI:
    enabled: true
    tls: true
    ingressClassName: nginx
    hostname: api.cas.chainloop.dev
    annotations:
      nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      # limit the size of the files that go through the proxy
      # 0 means to not check the size of the request so we do not get 413 error.
      # For now we are going to set a limit on 100MB files
      # Even though we send data in chunks of 1MB, this size refers to all the data sent in the streaming connection
      nginx.ingress.kubernetes.io/proxy-body-size: "100m"

Remember, once you have set up your domain, make sure you use the CLI pointing to it instead of the defaults.

Connect to an external PostgreSQL database

# Disable built-in DB
postgresql:
  enabled: false

# Provide with external connection
controlplane:
  externalDatabase:
    host: 1.2.3.4
    port: 5432
    user: chainloop
    password: [REDACTED]
    database: chainloop-controlplane-prod

Alternatively, if you are using Google Cloud SQL and you are running Chainloop in Google Kubernetes Engine. You can connect instead via a proxy

This method can also be easily enabled in this chart by doing

# Disable built-in DB
postgresql:
  enabled: false

# Provide with external connection
controlplane:
  sqlProxy:
    # Inject the proxy sidecar
    enabled: true
    ## @param controlplane.sqlProxy.connectionName Google Cloud SQL connection name
    connectionName: "my-sql-instance"
  # Then you'll need to configure your DB settings to use the proxy IP address
  externalDatabase:
    host: [proxy-sidecar-ip-address]
    port: 5432
    user: chainloop
    password: [REDACTED]
    database: chainloop-controlplane-prod

Use AWS secrets manager

Instead of using Hashicorp Vault (default), you can use AWS Secrets Manager by adding these settings in your values.yaml file

secretsBackend:
  backend: awsSecretManager
  awsSecretManager:
    accessKey: [KEY]
    secretKey: [SECRET]
    region: [REGION]

Use GCP secret manager

Or Google Cloud Secret Manager with the following settings

secretsBackend:
  backend: gcpSecretManager
  gcpSecretManager:
    projectId: [PROJECT_ID]
    serviceAccountKey: [KEY]

Use Azure KeyVault

Azure KeyVault is also supported

secretsBackend:
  backend: azureKeyVault
  azureKeyVault:
    tenantID: [TENANT_ID] # Active Directory Tenant ID
    clientID: [CLIENT_ID] # Registered application / service principal client ID
    clientSecret: [CLIENT_SECRET] # Service principal client secret
    vaultURI: [VAULT URI] # Azure Key Vault URL

Send exceptions to Sentry

You can configure different sentry projects for both the controlplane and the artifact CAS

# for controlplane
controlplane:
  ...
  sentry:
    enabled: true
    dsn: [your secret sentry project DSN URL]
    environment: production
# Artifact CAS
cas:
  ...
  sentry:
    enabled: true
    dsn: [your secret sentry project DSN URL]
    environment: production

Enable Prometheus Monitoring in GKE

Chainloop exposes Prometheus compatible /metrics endpoints that can be easily scraped by a Prometheus data collector Server.

Google Cloud has a managed Prometheus offering that could be easily enabled by setting --set GKEMonitoring.enabled=true. This will inject the required PodMonitoring custom resources.

Configure Chainloop CLI to point to your instance

Once you have your instance of Chainloop deployed, you need to configure the CLI to point to both the CAS and the Control plane gRPC APIs like this.

chainloop config save \
  --control-plane my-controlplane.acme.com:443 \
  --artifact-cas cas.acme.com:443

Parameters

Common parameters

NameDescriptionValue
kubeVersionOverride Kubernetes version""
developmentDeploys Chainloop pre-configured FOR DEVELOPMENT ONLY. It includes a Vault instance in development mode and pre-configured authentication certificates and passphrasesfalse
GKEMonitoring.enabledEnable GKE podMonitoring (prometheus.io scrape) to scrape the controlplane and CAS /metrics endpointsfalse

Secrets Backend

NameDescriptionValue
secretsBackend.backendSecrets backend type ("vault", "awsSecretManager" or "gcpSecretManager", "azureKeyVault")vault
secretsBackend.secretPrefixPrefix that will be pre-pended to all secrets in the storage backendchainloop
secretsBackend.vault.addressVault address
secretsBackend.vault.tokenVault authentication token
secretsBackend.awsSecretManager.accessKeyAWS Access KEY ID
secretsBackend.awsSecretManager.secretKeyAWS Secret Key
secretsBackend.awsSecretManager.regionAWS Secrets Manager Region
secretsBackend.gcpSecretManager.projectIdGCP Project ID
secretsBackend.gcpSecretManager.serviceAccountKeyGCP Auth Key
secretsBackend.azureKeyVault.tenantIDActive Directory Tenant ID
secretsBackend.azureKeyVault.clientIDRegistered application / service principal client ID
secretsBackend.azureKeyVault.clientSecretService principal client secret
secretsBackend.azureKeyVault.vaultURIAzure Key Vault URL

Authentication

NameDescriptionValue
casJWTPrivateKeyECDSA (ES512) private key used for Controlplane <-> CAS Authentication""
casJWTPublicKeyECDSA (ES512) public key""

Control Plane

NameDescriptionValue
controlplane.replicaCountNumber of replicas2
controlplane.image.repositoryFQDN uri for the imageghcr.io/chainloop-dev/chainloop/control-plane
controlplane.image.tagImage tag (immutable tags are recommended). If no set chart.appVersion will be used
controlplane.tlsConfig.secret.namename of a secret containing TLS certificate to be used by the controlplane grpc server.""
controlplane.pluginsDirDirectory where to look for plugins/plugins

Control Plane Database

NameDescriptionValue
controlplane.externalDatabaseExternal PostgreSQL configuration. These values are only used when postgresql.enabled is set to false
controlplane.externalDatabase.hostDatabase host""
controlplane.externalDatabase.portDatabase port number5432
controlplane.externalDatabase.userNon-root username""
controlplane.externalDatabase.databaseDatabase name""
controlplane.externalDatabase.passwordPassword for the non-root username""
controlplane.sqlProxy.enabledEnable sidecar to connect to DB via Google Cloud SQL proxyfalse
controlplane.sqlProxy.connectionNameGoogle Cloud SQL connection name""
controlplane.sqlProxy.resourcesSidecar container resources{}

Control Plane Authentication

NameDescriptionValue
controlplane.auth.passphrasePassphrase used to sign the Auth Tokens generated by the controlplane. Leave empty for auto-generation""
controlplane.auth.oidc.urlFull authentication path, it should match the issuer URL of the Identity provider (IDp)""
controlplane.auth.oidc.clientIDOIDC IDp clientID""
controlplane.auth.oidc.clientSecretOIDC IDp clientSecret""

Control Plane Networking

NameDescriptionValue
controlplane.service.typeService typeClusterIP
controlplane.service.portService port80
controlplane.service.targetPortService target Porthttp
controlplane.service.nodePorts.httpNode port for HTTP. NOTE: choose port between <30000-32767>
controlplane.serviceAPI.typeService typeClusterIP
controlplane.serviceAPI.portService port80
controlplane.serviceAPI.targetPortService target Portgrpc
controlplane.serviceAPI.annotationsService annotations
controlplane.serviceAPI.nodePorts.httpNode port for HTTP. NOTE: choose port between <30000-32767>
controlplane.ingress.enabledEnable ingress record generation for %%MAIN_CONTAINER_NAME%%false
controlplane.ingress.pathTypeIngress path typeImplementationSpecific
controlplane.ingress.hostnameDefault host for the ingress recordcp.dev.local
controlplane.ingress.ingressClassNameIngressClass that will be be used to implement the Ingress (Kubernetes 1.18+)""
controlplane.ingress.pathDefault path for the ingress record/
controlplane.ingress.annotationsAdditional annotations for the Ingress resource. To enable certificate autogeneration, place here your cert-manager annotations.{}
controlplane.ingress.tlsEnable TLS configuration for the host defined at controlplane.ingress.hostname parameterfalse
controlplane.ingress.selfSignedCreate a TLS secret for this ingress record using self-signed certificates generated by Helmfalse
controlplane.ingress.extraHostsAn array with additional hostname(s) to be covered with the ingress record[]
controlplane.ingress.extraPathsAn array with additional arbitrary paths that may need to be added to the ingress under the main host[]
controlplane.ingress.extraTlsTLS configuration for additional hostname(s) to be covered with this ingress record[]
controlplane.ingress.secretsCustom TLS certificates as secrets[]
controlplane.ingress.extraRulesAdditional rules to be covered with this ingress record[]
controlplane.ingressAPI.enabledEnable ingress record generation for %%MAIN_CONTAINER_NAME%%false
controlplane.ingressAPI.pathTypeIngress path typeImplementationSpecific
controlplane.ingressAPI.hostnameDefault host for the ingress recordapi.cp.dev.local
controlplane.ingressAPI.ingressClassNameIngressClass that will be be used to implement the Ingress (Kubernetes 1.18+)""
controlplane.ingressAPI.pathDefault path for the ingress record/
controlplane.ingressAPI.annotationsAdditional annotations for the Ingress resource. To enable certificate autogeneration, place here your cert-manager annotations.
controlplane.ingressAPI.tlsEnable TLS configuration for the host defined at controlplane.ingress.hostname parameterfalse
controlplane.ingressAPI.selfSignedCreate a TLS secret for this ingress record using self-signed certificates generated by Helmfalse
controlplane.ingressAPI.extraHostsAn array with additional hostname(s) to be covered with the ingress record[]
controlplane.ingressAPI.extraPathsAn array with additional arbitrary paths that may need to be added to the ingress under the main host[]
controlplane.ingressAPI.extraTlsTLS configuration for additional hostname(s) to be covered with this ingress record[]
controlplane.ingressAPI.secretsCustom TLS certificates as secrets[]
controlplane.ingressAPI.extraRulesAdditional rules to be covered with this ingress record[]

Controlplane Misc

NameDescriptionValue
controlplane.resources.limits.cpuContainer resource limits CPU250m
controlplane.resources.limits.memoryContainer resource limits memory512Mi
controlplane.resources.requests.cpuContainer resource requests CPU250m
controlplane.resources.requests.memoryContainer resource requests memory512Mi
controlplane.autoscaling.enabledEnable deployment autoscalingfalse
controlplane.autoscaling.minReplicasMinimum number of replicas1
controlplane.autoscaling.maxReplicasMaximum number of replicas100
controlplane.autoscaling.targetCPUUtilizationPercentageTarget CPU percentage80
controlplane.autoscaling.targetMemoryUtilizationPercentageTarget CPU memory80
controlplane.sentry.enabledEnable sentry.io alertingfalse
controlplane.sentry.dsnDSN endpoint https://docs.sentry.io/product/sentry-basics/dsn-explainer/""
controlplane.sentry.environmentEnvironment tagproduction

Artifact Content Addressable (CAS) API

NameDescriptionValue
cas.replicaCountNumber of replicas2
cas.image.repositoryFQDN uri for the imageghcr.io/chainloop-dev/chainloop/artifact-cas
cas.image.tagImage tag (immutable tags are recommended). If no set chart.appVersion will be used
cas.tlsConfig.secret.namename of a secret containing TLS certificate to be used by the controlplane grpc server.""

CAS Networking

NameDescriptionValue
cas.service.typeService typeClusterIP
cas.service.portService port80
cas.service.targetPortService target Porthttp
cas.service.nodePorts.httpNode port for HTTP. NOTE: choose port between <30000-32767>
cas.serviceAPI.typeService typeClusterIP
cas.serviceAPI.portService port80
cas.serviceAPI.targetPortService target Portgrpc
cas.serviceAPI.annotationsService annotations
cas.serviceAPI.nodePorts.httpNode port for HTTP. NOTE: choose port between <30000-32767>
cas.ingress.enabledEnable ingress record generation for %%MAIN_CONTAINER_NAME%%false
cas.ingress.pathTypeIngress path typeImplementationSpecific
cas.ingress.hostnameDefault host for the ingress recordcas.dev.local
cas.ingress.ingressClassNameIngressClass that will be be used to implement the Ingress (Kubernetes 1.18+)""
cas.ingress.pathDefault path for the ingress record/
cas.ingress.annotationsAdditional annotations for the Ingress resource. To enable certificate autogeneration, place here your cert-manager annotations.{}
cas.ingress.tlsEnable TLS configuration for the host defined at controlplane.ingress.hostname parameterfalse
cas.ingress.selfSignedCreate a TLS secret for this ingress record using self-signed certificates generated by Helmfalse
cas.ingress.extraHostsAn array with additional hostname(s) to be covered with the ingress record[]
cas.ingress.extraPathsAn array with additional arbitrary paths that may need to be added to the ingress under the main host[]
cas.ingress.extraTlsTLS configuration for additional hostname(s) to be covered with this ingress record[]
cas.ingress.secretsCustom TLS certificates as secrets[]
cas.ingress.extraRulesAdditional rules to be covered with this ingress record[]
cas.ingressAPI.enabledEnable ingress record generation for %%MAIN_CONTAINER_NAME%%false
cas.ingressAPI.pathTypeIngress path typeImplementationSpecific
cas.ingressAPI.hostnameDefault host for the ingress recordapi.cas.dev.local
cas.ingressAPI.ingressClassNameIngressClass that will be be used to implement the Ingress (Kubernetes 1.18+)""
cas.ingressAPI.pathDefault path for the ingress record/
cas.ingressAPI.annotationsAdditional annotations for the Ingress resource. To enable certificate autogeneration, place here your cert-manager annotations.
cas.ingressAPI.tlsEnable TLS configuration for the host defined at controlplane.ingress.hostname parameterfalse
cas.ingressAPI.selfSignedCreate a TLS secret for this ingress record using self-signed certificates generated by Helmfalse
cas.ingressAPI.extraHostsAn array with additional hostname(s) to be covered with the ingress record[]
cas.ingressAPI.extraPathsAn array with additional arbitrary paths that may need to be added to the ingress under the main host[]
cas.ingressAPI.extraTlsTLS configuration for additional hostname(s) to be covered with this ingress record[]
cas.ingressAPI.secretsCustom TLS certificates as secrets[]
cas.ingressAPI.extraRulesAdditional rules to be covered with this ingress record[]

CAS Misc

NameDescriptionValue
cas.resources.limits.cpuContainer resource limits CPU250m
cas.resources.limits.memoryContainer resource limits memory512Mi
cas.resources.requests.cpuContainer resource requests CPU250m
cas.resources.requests.memoryContainer resource requests memory512Mi
cas.autoscaling.enabledEnable deployment autoscalingfalse
cas.autoscaling.minReplicasMinimum number of replicas1
cas.autoscaling.maxReplicasMaximum number of replicas100
cas.autoscaling.targetCPUUtilizationPercentageTarget CPU percentage80
cas.autoscaling.targetMemoryUtilizationPercentageTarget CPU memory80
cas.sentry.enabledEnable sentry.io alertingfalse
cas.sentry.dsnDSN endpoint https://docs.sentry.io/product/sentry-basics/dsn-explainer/""
cas.sentry.environmentEnvironment tagproduction

Dependencies

NameDescriptionValue
postgresql.enabledSwitch to enable or disable the PostgreSQL helm charttrue
postgresql.auth.enablePostgresUserAssign a password to the "postgres" admin user. Otherwise, remote access will be blocked for this userfalse
postgresql.auth.usernameName for a custom user to createchainloop
postgresql.auth.passwordPassword for the custom user to createchainlooppwd
postgresql.auth.databaseName for a custom database to createchainloop-cp
postgresql.auth.existingSecretName of existing secret to use for PostgreSQL credentials""
vault.server.dev.enabledEnable development mode (unsealed, in-memory, insecure)true
vault.server.dev.devRootTokenConnection tokennotapassword

License

Copyright © 2023 The Chainloop Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.