cert-manager-startupapicheck

Start a cert-manager-startupapicheck container

Note: cert-manager-startupapicheck is designed to run inside a Kubernetes cluster as part of a full cert-manager deployment, typically as a Helm post-install Job. The following standalone Docker command displays the available configuration options.

Run the following command and replace <tag> with the image variant you want to run.

docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:<tag> --help

Run with an external kubeconfig

When running outside a cluster, mount your kubeconfig and pass --kubeconfig:

docker run --rm \
  -v ~/.kube/config:/kube/config:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:<tag> \
  check api --kubeconfig /kube/config --wait 60s

Note: Running outside a cluster against a local kubeconfig will fail unless cert-manager is already deployed and the Kubernetes API is reachable. The expected failure mode is a connection or API error, not a crash.

Command-line flags

The startupapicheck binary accepts configuration via command-line flags. When running via Docker, commonly used flags include:

Example:

# Mount kubeconfig and pass via --kubeconfig flag
docker run --rm -v ~/.kube/config:/kube/config:ro \
  registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:<tag> \
  check api --kubeconfig /kube/config

# Enable verbose logging
docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:<tag> -v 2 --help

Common cert-manager-startupapicheck use cases

Validate cert-manager API availability

The primary purpose of startupapicheck is to verify that cert-manager's custom API resources are registered and the webhook is reachable before post-install steps proceed. It probes the cert-manager API by attempting to create a CertificateRequest resource and checking for a valid admission response.

When deployed via Helm, cert-manager automatically runs startupapicheck as a post-install Job. You can also run it manually to verify a running cert-manager installation.

First, create the required service account and RBAC. This is handled automatically by Helm but must be created manually when using kubectl apply:

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: ServiceAccount
metadata:
  name: cert-manager-startupapicheck
  namespace: cert-manager
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cert-manager-startupapicheck
rules:
  - apiGroups: ["cert-manager.io"]
    resources: ["certificaterequests"]
    verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cert-manager-startupapicheck
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cert-manager-startupapicheck
subjects:
  - kind: ServiceAccount
    name: cert-manager-startupapicheck
    namespace: cert-manager
EOF

Then run the Job:

kubectl apply -f - <<'EOF'
apiVersion: batch/v1
kind: Job
metadata:
  name: cert-manager-startupapicheck
  namespace: cert-manager
spec:
  backoffLimit: 4
  template:
    spec:
      restartPolicy: OnFailure
      serviceAccountName: cert-manager-startupapicheck
      containers:
        - name: startupapicheck
          image: registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:<tag>
          args:
            - check
            - api
            - --wait=60s
          env:
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
EOF

A successful run produces output similar to:

The cert-manager API is ready

The Job exits 0 on success and the pod reaches Completed status.

Use as a Helm post-install hook

In production deployments, startupapicheck runs automatically as a Helm post-install hook. When using the DHI Helm chart, no extra configuration is required — the hook is pre-configured to use the DHI image. The hook blocks the helm install command from returning until cert-manager is confirmed ready:

helm install my-cert-manager oci://registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-chart --version 1.20.4 \
  --namespace cert-manager \
  --set "global.imagePullSecrets[0].name=helm-pull-secret" \
  --set "installCRDs=true"

If startupapicheck fails, the Helm installation is marked as failed and the release is rolled back.

Monitor readiness in CI/CD pipelines

startupapicheck is useful as a readiness gate in CI/CD pipelines after deploying cert-manager. Run the Job and wait for its completion before proceeding with certificate issuance steps:

# Wait for the startupapicheck Job to complete
kubectl wait --for=condition=complete \
  job/cert-manager-startupapicheck \
  -n cert-manager --timeout=120s

# Then proceed with certificate issuance
kubectl apply -f my-certificate.yaml

End-to-end startupapicheck deployment walkthrough

The following steps demonstrate a complete deployment and verification, validated against cert-manager v1.20.4 and registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:1-debian13.

Prerequisites: A running Kubernetes cluster with kubectl and helm access. All cert-manager components must use Ghost hardened images. The recommended way to install all components together is via the DHI Helm chart, which deploys registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-controller, registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-cainjector, registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-webhook, registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck, and registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-acmesolver automatically:

# Create the namespace and imagePullSecret first
kubectl create namespace cert-manager

kubectl create secret docker-registry helm-pull-secret \
  --docker-server=registry.ghost-prod.alphabravo.io \
  --docker-username=<your-docker-username> \
  --docker-password=<your-docker-password> \
  -n cert-manager

# Install all cert-manager components using the DHI Helm chart
helm install my-cert-manager oci://registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-chart --version 1.20.4 \
  --namespace cert-manager \
  --set "global.imagePullSecrets[0].name=helm-pull-secret" \
  --set "installCRDs=true"

# Wait for all pods to be ready
kubectl wait --for=condition=Ready pod --all -n cert-manager --timeout=120s

Step 1: Verify the startupapicheck Job ran and completed

kubectl get job -n cert-manager | grep startupapicheck
# NAME                                    COMPLETIONS   DURATION   AGE
# my-cert-manager-startupapicheck         1/1           12s        2m

Step 2: Inspect the Job logs

kubectl logs job/my-cert-manager-startupapicheck -n cert-manager
# The cert-manager API is ready

Note: When deployed via Helm with installCRDs=true, the startupapicheck Job first polls while cainjector injects the webhook CA bundle. You may see repeated "Not ready" messages referencing x509: certificate signed by unknown authority for 60–90 seconds before the Job completes. This is expected behavior. Once cainjector finishes CA injection, the Job completes and is automatically cleaned up by Helm.

Step 3: Confirm the DHI image is in use

kubectl get job my-cert-manager-startupapicheck -n cert-manager \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
# registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:1-debian13

Step 4: Run a standalone check against the live cluster

kubectl apply -f - <<'EOF'
apiVersion: batch/v1
kind: Job
metadata:
  name: startupapicheck-manual
  namespace: cert-manager
spec:
  backoffLimit: 2
  template:
    spec:
      restartPolicy: OnFailure
      serviceAccountName: my-cert-manager-startupapicheck
      containers:
        - name: startupapicheck
          image: registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck:1-debian13
          args:
            - check
            - api
            - --wait=60s
          env:
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
EOF

kubectl wait --for=condition=complete \
  job/startupapicheck-manual \
  -n cert-manager --timeout=120s

Expected: job.batch/startupapicheck-manual condition met

Step 5: Clean up

kubectl delete job startupapicheck-manual -n cert-manager
kubectl delete clusterrolebinding cert-manager-startupapicheck
kubectl delete clusterrole cert-manager-startupapicheck
kubectl delete serviceaccount cert-manager-startupapicheck -n cert-manager
helm uninstall my-cert-manager -n cert-manager
kubectl delete secret helm-pull-secret -n cert-manager
kubectl delete namespace cert-manager

# CRDs are kept by Helm resource policy — delete manually if needed
kubectl delete crd \
  challenges.acme.cert-manager.io \
  orders.acme.cert-manager.io \
  certificaterequests.cert-manager.io \
  certificates.cert-manager.io \
  clusterissuers.cert-manager.io \
  issuers.cert-manager.io

Official images vs Ghost hardened images

Image variants

Ghost hardened images come in different variants depending on their intended use. Image variants are identified by their tag.

• Runtime variants are designed to run startupapicheck in production. These images are intended to be used either directly or as the FROM image in the final stage of a multi-stage build. These images typically:

  • Run as a nonroot user
  • Do not include a shell or a package manager
  • Contain only the minimal set of libraries needed to run the binary

• Build-time variants typically include dev in the tag name and are intended for use in the first stage of a multi-stage Dockerfile. These images typically:

  • Run as the root user
  • Include a shell and package manager
  • Are used to build or compile applications

To view the image variants and get more information about them, select the Tags tab for this repository, and then select a tag.

Note: cert-manager consists of multiple components (controller, acmesolver, cainjector, webhook, startupapicheck) that work together. Each component is available as a separate Ghost hardened image for deployment flexibility.

FIPS variants considerations

FIPS variants (1-fips, 1-debian13-fips, 1.20-fips, 1.20.4-fips, 1.20.4-debian13-fips) are available on Docker Hub and carry CIS, FIPS, and STIG compliance badges with 0 vulnerabilities. Pulling FIPS variants requires a Docker subscription — the tags return 401 without one.

The FIPS image runs with the following environment variables that enable FIPS mode:

• GODEBUG=fips140=on — enables FIPS 140 mode in the Go runtime
• GOFIPS140=v1.0.0 — specifies the FIPS 140 Go module version
• OPENSSL_CONF=/usr/lib/ssl/openssl.cnf — points to the FIPS-enabled OpenSSL configuration
• OPENSSL_MODULES=/usr/lib/aarch64-linux-gnu/ossl-modules — path to OpenSSL FIPS modules
• OPENSSL_VERSION=3.5.5 — OpenSSL version used

Note: The following behaviours are documented from cert-manager source code. They cannot be tested without a Docker subscription, a FIPS-enabled Kubernetes cluster, and a live DNS server.

When using FIPS variants, be aware of the following cert-manager behaviours involving non-FIPS-compliant algorithms:

1. RFC2136 DNS-01 solver — The tsigHMACProvider.Generate function uses SHA1 and MD5 for TSIG authentication, which are forbidden by FIPS and will cause the application to panic. To mitigate, specify a FIPS-approved algorithm in your Issuer or ClusterIssuer:

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: example-rfc2136
   spec:
     acme:
       server: https://acme-v02.api.letsencrypt.org/directory
       email: admin@example.com
       privateKeySecretRef:
         name: example-account-key
       solvers:
       - dns01:
           rfc2136:
             nameserver: 203.0.113.53:53
             tsigKeyName: example-com-key
             tsigAlgorithm: HMACSHA512
             tsigSecretSecretRef:
               name: tsig-secret
               key: tsig-secret-key
   

2. Legacy TLS cipher suites (RC4, ChaCha20, SHA1) — cert-manager includes these for compatibility with older DNS servers. They are supported but not preferred; modern clients negotiate stronger ciphers automatically.

3. PKCS#12 legacy profiles (DES and RC2) — cert-manager supports LegacyDESPKCS12Profile and LegacyRC2PKCS12Profile for backward compatibility. Use the Modern 2023 Certificate profile as a FIPS-compliant alternative, or avoid keystores entirely.

4. CHACHA20_POLY1305 cipher — If the client supports TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, the application will panic. Ensure your FIPS-compliant stack does not negotiate this cipher.

Migrate to a Ghost hardened image

To migrate your application to a Ghost hardened image, you must update your Dockerfile or Kubernetes manifests. At minimum, update the base image in your existing deployment to a Ghost hardened image. Common changes are listed in the following table of migration notes.

The following steps outline the general migration process.

1. Find hardened images for your app. The cert-manager-startupapicheck hardened image may have several variants. Inspect the image tags and find the image variant that meets your needs. Remember that cert-manager requires multiple components to function properly.

2. Update the image reference in your Helm values or Kubernetes manifests. If using Helm, set the image in your values.yaml:

   startupapicheck:
     image:
       repository: registry.ghost-prod.alphabravo.io/ghost-base/cert-manager-startupapicheck
       tag: "<tag>"
   

3. For custom Dockerfiles, update the runtime image. Ensure all stages in your Dockerfile use hardened images. Intermediary stages typically use dev-tagged images; your final runtime stage should use a non-dev image variant.

4. Verify component compatibility. Ensure all cert-manager components (controller, webhook, cainjector, acmesolver, startupapicheck) are using compatible versions. The startupapicheck Job runs after all other components are deployed.

5. Confirm the check passes. After migration, inspect the completed Job logs to confirm The cert-manager API is ready appears in the output.

Troubleshoot migration

General debugging

The hardened images intended for runtime don't contain a shell nor any tools for debugging. The recommended method for debugging applications built with Ghost hardened images is to use Docker Debug to attach to these containers. Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session.

Permissions

By default, image variants intended for runtime run as the nonroot user. Ensure that necessary files and directories are accessible to the nonroot user.

cert-manager-startupapicheck requires create permission on certificaterequests in the cert-manager.io API group to probe API availability. Ensure your RBAC configuration grants the cert-manager-startupapicheck service account this permission.

Privileged ports

startupapicheck does not bind to any network ports — it only makes outbound connections to the Kubernetes API server. Privileged port restrictions do not apply to this component.

No shell

By default, image variants intended for runtime don't contain a shell. Use dev images in build stages to run shell commands and then copy any necessary artifacts into the runtime stage. In addition, use Docker Debug to debug containers with no shell.

Entry point

Ghost hardened images may have different entry points than standard cert-manager images. Use docker inspect to inspect entry points for Ghost hardened images and update your Kubernetes deployment if necessary.