Skip to main content
Version: Weekly Build

Cluster Ingress CA Options

Codesphere supports two ways of issuing certificates for ingress traffic within the cluster, selected with codesphere.certIssuer.type.

Available issuer types​

certIssuer.typeDescriptionExample usage scenario
self-signed (default)Generate a new self-signed CA locally, or supply your own CA certificate and key (for example your organization's existing CA) under cluster.certificates.ca.Quick start and test environments by default; enterprises with a central CA can supply their own CA material instead of generating one.
acmeUse the ACME protocol (for example Let's Encrypt) for automated certificate issuance and renewal.Automated certificate management, cloud-native environments.

How to configure​

In config.yaml, select the issuer with codesphere.certIssuer.type. The legacy cluster.certificates.ca block holds the CA material for the self-signed type; ACME is configured entirely under codesphere.certIssuer.acme and cluster.certificates.override.

Self-signed (default, or your own CA)​

codesphere:
  certIssuer:
    type: self-signed
cluster:
  certificates:
    ca:
      algorithm: RSA # or ECDSA
      keySizeBits: 2048 # or 4096, etc.
      certPem: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----

To bring your own CA (for example an organization CA) instead of letting OMS generate one, supply your CA's certificate as certPem and its private key as the selfSignedCaKeyPem vault secret below.

The private key for the CA must be stored in your SOPS vault (prod.vault.yaml) under the key selfSignedCaKeyPem:

secrets:
  - name: selfSignedCaKeyPem
    file:
      name: ca.key
      content: |
        -----BEGIN PRIVATE KEY-----
        ...
        -----END PRIVATE KEY-----

ACME​

For ACME, provide the ACME server URL, your email, and optionally an EAB (External Account Binding) key ID. The ACME private key and EAB key are secrets and must be added to your SOPS vault.

Example: ACME (Let's Encrypt, with a Cloudflare DNS solver)

codesphere:
  certIssuer:
    type: acme
    acme:
      server: https://acme-v02.api.letsencrypt.org/directory
      email: [email protected]
      eabKeyId: <optional-eab-key-id>
cluster:
  certificates:
    override:
      issuers:
        acme:
          # DNS solver configuration (override in your deployment config):
          dnsSolver:
            config:
              cloudflare:
                apiTokenSecretRef:
                  name: acme-solver
                  key: api-token
          solverSecret:
            name: acme-solver
            data:
              api-token: <api-token>

The EAB MAC key, if used, must be stored under the key acmeEabMacKey:

secrets:
  - name: acmeEabMacKey
    fields:
      key: <your-eab-mac-key>

note

The DNS solver configuration must be added as an override in your deployment config, matching your DNS provider (for example Cloudflare or Route53). For Cloudflare, use the apiTokenSecretRef and solverSecret fields as shown above.

Choosing the right option​

  • Self-signed (generated): Easiest to set up, but trust must be distributed to all users and devices.
  • Self-signed (your own CA): Recommended when you already operate a CA and want to leverage existing trust infrastructure.
  • ACME: Best for automated certificate issuance and renewal without operating your own CA.

Next​

See Gateway and load balancing for the gateway configuration these certificates are served from, and Networking, firewalls, and DNS for planning which issuer to use.