Skip to content

Latest commit

 

History

History
137 lines (99 loc) · 5.54 KB

README.md

File metadata and controls

137 lines (99 loc) · 5.54 KB
Raw

Docker Image CI

Kubernetes Cert Manager Webhook for Name.com

Cert Manager Webhook for Name.com is an ACME webhook solver for cert-manager that enables the use of DNS01 challenges with Name.com as the DNS provider, via the Name.com API.

🧰 Requirements

📦 Installation

1. Webhook

Use a local checkout of this repository and install the webhook with Helm:

helm install --namespace cert-manager cert-manager-webhook-namecom  ./deploy/cert-manager-webhook-namecom/

🔔 Note: The webhook should be deployed into the same namespace as cert-manager. If you changed that, you should update the certManager.namespace value in the deploy template file, values.yaml, before installation.

Uninstallation

You can also remove the webhook using Helm:

helm uninstall --namespace cert-manager cert-manager-webhook-namecom

2. API token secret

Create a Kubernetes Secret to store the value of your Name.com API token:

kubectl create secret generic namedotcom-credentials --from-literal=api-token=<your API token> --namespace cert-manager

💡 Note: The secret should also be in the same namespace as cert-manager. If you change the name of the secret or key, don't forget to use those values in the Issuer below.

3. Certificate issuer

Define a cert-manager Issuer (or ClusterIssuer) resource that uses the webhook as the solver. Create a file called, e.g. cert-issuer.yml, and use the following content as the template:

cert-issuer.yml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-namecom
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    # For production use this URL instead:
    # server: https://acme-v02.api.letsencrypt.org/directory
    email: <[email protected]>
    privateKeySecretRef:
      name: letsencrypt-account-key
    solvers:
    - dns01:
        webhook:
          groupName: acme.name.com
          solverName: namedotcom
          config:
            username: <your Name.com username>
            apitokensecret:
              name: namedotcom-credentials
              key: api-token

💡 Note: The config key for the webhook defines your Name.com API credentials—the apitokensecret.name and apitokensecret.key values must match those for your secret, above.

Apply the file to your cluster to create the resource:

kubectl apply -f cert-issuer.yaml

🔔Note: If you defined an Issuer rather than a ClusterIssuer, you should create it in the same namespace as cert-manager.

📜 Issue a certificate

Create a certificate by defining a cert-manager Certificate resource and applying it to your cluster:

example-cert.yml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
spec:
  dnsNames:
    - test.example.com
  issuerRef:
    name: letsencrypt-namecom
    kind: ClusterIssuer
  secretName: example-cert

💡 Note: If you defined an Issuer rather than a ClusterIssuer, you can omit the issuerRef.kind key.

kubectl apply -f example-cert.yml

After allowing a short period for the challenge, order and issuing process to complete, the certificate should be available for use: 🥳

$ kubectl get certificate example-com
NAME          READY   SECRET             AGE
example-com   True    example-com-cert   1m12s

🔧 Development

Running the test suite

All DNS providers must run the DNS01 provider conformance testing suite, else they will have undetermined behaviour when used with cert-manager.

✔️ It is essential that you configure and run the test suite when creating a DNS01 webhook.

Before running the test suite, you must supply valid credentials for the Name.com API. See the test data README for more information.

You can run the test suite with:

TEST_ZONE_NAME=example.com. make test

🔔 Note: example.com must also be a domain registered to your Name.com and configured with Name.com's default nameservers so that DNS records can be managed via Name.com DNS.