cluster-ingress-ca-options

Cluster Ingress CA Options

Codesphere now supports multiple options for issuing and managing the Cluster Ingress CA, which is used to sign certificates for all ingress traffic within the cluster. This flexibility allows you to choose the best approach for your organization's security and operational requirements.

Available Issuer Options

Option	Description	Example Usage Scenario
Self-Signed (default)	Generate a new self-signed CA locally.	Quick start, test, or when no org CA is available.
Organization CA	Use your organization's existing CA or intermediate CA to sign ingress certificates.	Enterprise environments with central CA management.
External Issuer	Integrate with an external certificate authority (e.g., HashiCorp Vault, AWS PCA, Let's Encrypt).	Automated cert management, cloud-native environments.

How to Configure

How to Configure

In your config.yaml, you can select the certificate issuer using the codesphere.certIssuer option. The legacy cluster.certificates.ca block is used for self-signed and organization CA, while external issuers are configured via codesphere.certIssuer.

Self-Signed or Organization CA:

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

certIssuer Options:

The codesphere.certIssuer field supports the following types:

• self-signed: Use a self-signed CA (default, no ACME integration)
• acme: Use ACME protocol (e.g., Let's Encrypt) for automated certificate management

For ACME, you must 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 config.

Example: Self-Signed

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

SOPS Vault Secret Requirements for Self-Signed CA:

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

Example SOPS Vault Entry:

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

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

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

SOPS Vault Secret Requirements for ACME:

• The EAB MAC key (if used) must be stored under the key: acmeEabMacKey.

Example SOPS Vault Entry:

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 (e.g., Cloudflare, Route53, etc.).
• For Cloudflare, use the apiTokenSecretRef and solverSecret as shown above.

Note:

• For self-signed and organization CA, you must provide both the private key and certificate PEM blocks.
• For external issuers, the integration fields depend on the external CA provider. Refer to your provider's documentation for required fields.

Choosing the Right Option

• Self-Signed: Easiest to set up, but trust must be distributed to all users/devices.
• Organization CA: Recommended for production and enterprise, leverages existing trust infrastructure.
• External Issuer: Best for automated certificate management and cloud-native workflows.