From 985bad515f835421c238bc3ebceb16c817bca23f Mon Sep 17 00:00:00 2001 From: Remy Moll Date: Mon, 22 Apr 2024 15:50:04 +0200 Subject: [PATCH] improve documentation --- .github/workflows/test-kubernetes.yaml | 2 +- README.md | 177 ++++++++++++++++--------- src/main_test.go | 2 + 3 files changed, 114 insertions(+), 67 deletions(-) diff --git a/.github/workflows/test-kubernetes.yaml b/.github/workflows/test-kubernetes.yaml index 084cd1b1c..4a0d93b8c 100644 --- a/.github/workflows/test-kubernetes.yaml +++ b/.github/workflows/test-kubernetes.yaml @@ -26,6 +26,7 @@ jobs: - name: Install cert-manager and patch upstream dns servers run: | kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml + # Patch cert-manager to use DNSimple's nameservers for faster propagation-checks kubectl patch deployment cert-manager -n cert-manager --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--dns01-recursive-nameservers=ns1.dnsimple.com:53"}]' @@ -50,7 +51,6 @@ jobs: --set clusterIssuer.staging.enabled=true \ --set clusterIssuer.email="noreply@$DNSIMPLE_ZONE_NAME" \ --set image.tag=commit-${{ github.sha }} - kubectl get secrets cert-manager-webhook-dnsimple -o yaml - name: Wait for cert-manager-webhook-dnsimple to be ready diff --git a/README.md b/README.md index b5909e5cf..9ee446d84 100644 --- a/README.md +++ b/README.md @@ -2,95 +2,140 @@ A [cert-manager][2] ACME DNS01 solver webhook for [DNSimple][1]. + ## Pre-requisites - [cert-manager][2] >= 0.13 (The Helm chart uses the new API versions) - Kubernetes >= 1.17.x - Helm 3 (otherwise adjust the example below accordingly) -## Quickstart -Take note of your DNSimple API token from the account settings in the automation tab. Run the following commands replacing the API token / account ID placeholders and email address: - -```bash -$ helm repo add neoskop https://charts.neoskop.dev -$ helm install cert-manager-webhook-dnsimple \ - --namespace cert-manager \ - --dry-run \ - --set dnsimple.token='' \ - --set dnsimple.accountID='' # Only needed if using a User API token \ - --set clusterIssuer.production.enabled=true \ - --set clusterIssuer.staging.enabled=true \ - --set clusterIssuer.email=email@example.com \ - neoskop/cert-manager-webhook-dnsimple -``` - -_(Alternatively you can check out this repository and substitute neoskop/cert-manager-webhook-dnsimple with ./deploy/dnsimple)_ - -Afterwards issue a certificate: - -```bash -$ cat << EOF | kubectl apply -f - -apiVersion: cert-manager.io/v1 -kind: Certificate -metadata: - name: dnsimple-test - namespace: default -spec: - dnsNames: - - test.example.com - issuerRef: - name: cert-manager-webhook-dnsimple-production - kind: ClusterIssuer - secretName: dnsimple-test-tls -EOF -``` - -## Options +## Quickstart +1. Take note of your DNSimple API token from the account settings in the automation tab. + +2. Add the helm repo published under the [Github pages deployment of this repository][4]: + ```bash + $ helm repo add certmanager-webhook https://puzzle.github.io/cert-manager-webhook-dnsimple + ``` + +3. Install the application, replacing the API token and email placeholders: + ```bash + $ helm repo add certmanager-webhook https://puzzle.github.io/cert-manager-webhook-dnsimple + $ helm install cert-manager-webhook-dnsimple \ + --dry-run \ # remove once you are sure the values are correct + --namespace cert-manager \ + --set dnsimple.token='' \ + --set clusterIssuer.production.enabled=true \ + --set clusterIssuer.staging.enabled=true \ + --set clusterIssuer.email= \ + certmanager-webhook/cert-manager-webhook-dnsimple + ``` + Alternatively you can check out this repository and substitute the source of the install command with `./charts/cert-manager-webhook-dnsimple`. + +4. Afterwards you can issue a certificate: + ```bash + $ cat << EOF | kubectl apply -f - + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: dnsimple-test + spec: + dnsNames: + - test.example.com + issuerRef: + name: cert-manager-webhook-dnsimple-staging + kind: ClusterIssuer + secretName: dnsimple-test-tls + EOF + ``` + + +## Chart options The Helm chart accepts the following values: | name | required | description | default value | | ---------------------------------- | -------- | ----------------------------------------------- | --------------------------------------- | | `dnsimple.token` | ✔️ | DNSimple API Token | _empty_ | -| `dnsimple.accountID` | | DNSimple Account ID (required for User tokens) | _empty_ | -| `clusterIssuer.email` | | LetsEncrypt Admin Email | `name@example.com` | +| `dnsimple.accountID` | | DNSimple Account ID (required when `dnsimple.token` is a user-token) | _empty_ | +| `clusterIssuer.email` | | LetsEncrypt Admin Email | _empty_ | | `clusterIssuer.production.enabled` | | Create a production `ClusterIssuer` | `false` | | `clusterIssuer.staging.enabled` | | Create a staging `ClusterIssuer` | `false` | -| `image.repository` | ✔️ | Docker image for the webhook solver | `neoskop/cert-manager-webhook-dnsimple` | -| `image.tag` | ✔️ | Docker image tag of the solver | `latest` | +| `image.repository` | ✔️ | Docker image for the webhook solver | `ghcr.io/puzzle/cert-manager-webhook-dnsimple` | +| `image.tag` | ✔️ | Docker image tag of the solver | latest tagged docker build | | `image.pullPolicy` | ✔️ | Image pull policy of the solver | `IfNotPresent` | | `logLevel` | | Set the verbosity of the solver | _empty_ | -| `groupName` | ✔️ | Identifies the company that created the webhook | `acme.neoskop.de` | +| `groupName` | ✔️ | Identifies the company that created the webhook | _empty_ | | `certManager.namespace` | ✔️ | The namespace cert-manager was installed to | `cert-manager` | | `certManager.serviceAccountName` | ✔️ | The service account cert-manager runs under | `cert-manager` | -## Test suite - -All cert-manager webhooks have to pass the DNS01 provider conformance testing suite. To run that test suite on this plug-in download the test binaries: - -```bash -$ mkdir -p __main__/hack -$ wget -O- https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.14.1-linux-amd64.tar.gz | tar xz --strip-components=1 -C __main__/hack -``` - -Then set-up `testdata/dnsimple/config.json` and `testdata/dnsimple/dnsimple-token.yaml` according to the [README][3]. - -Execute the test suite replacing `TEST_ZONE_NAME` with a DNS name you have control over with your DNSimple account: - -```bash -# Mind the trailing dot in the TEST_ZONE_NAME value -$ TEST_ZONE_NAME=example.com. go test . -``` -## Release +## Testing +All cert-manager webhooks have to pass the DNS01 provider conformance testing suite. + +### Pull requests +Prerequisites for PRs are implemented as GitHub-actions. All tests should pass before a PR is merged: +- the `cert-manager` conformance suite is run with provided kubebuilder fixtures +- a custom test suite running on a working k8s cluster (using `minikube`) is executed as well + +### Local testing +#### Test suite +You can also run tests locally, as specified in the `Makefile`: + +1. Set-up `testdata/` according to its [README][3]. + - `dnsimple-token.yaml` should be filled with a valid token (for either the sandbox or production environment) + - `dnsimple.env` should contain the remaining environment variables (non sensitive) +2. Execute the test suite: + ```bash + make test + ``` +#### In-cluster testing +1. Install cert-manager: + ```bash + kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml + ``` +2. Install the webhook: + ```bash + helm install cert-manager-webhook-dnsimple \ + --namespace cert-manager \ + --set dnsimple.token='' \ + --set clusterIssuer.staging.enabled=true \ + ./charts/cert-manager-webhook-dnsimple + ``` +3. Test away... You can create a sample certificate to ensure the webhook is working correctly: + ```bash + kubectl apply -f - <<`. **We recommend using a specific version tag for production deployments instead.** + +Tagged images are considered stable, these are the ones referenced by the default helm values. + +### Helm releases +Helm charts are only released when significant changes occur. We encourage users to update the underlying image versions on their own. A new release can be triggered manually under the _actions_ tab and running `helm-release`. This only works if a new version was specified in the `Chart.yaml`. The new release will be appended to the [Github pages deployment][4]. + + +## Contributing +We welcome contributions. Please open an issue or a pull request. -After you committed all of your changes, run the following command to tag a new version and build and push a new Docker image tag as well as a new Helm chart: -```bash -$ ./scripts/release.sh -``` [1]: https://dnsimple.com/ [2]: https://cert-manager.io/docs/installation/kubernetes/ -[3]: ./testdata/dnsimple/README.md +[3]: ./testdata/README.md +[4]: https://puzzle.github.io/cert-manager-webhook-dnsimple diff --git a/src/main_test.go b/src/main_test.go index 9d7dc43ee..0ba05f4e5 100644 --- a/src/main_test.go +++ b/src/main_test.go @@ -24,6 +24,8 @@ func TestRunsSuite(t *testing.T) { dns.SetDNSName("puzzle.beer"), dns.SetUseAuthoritative(false), dns.SetDNSServer("ns1.dnsimple.com:53"), + // check against dnsimple nameservers for faster propagation + // dns.SetStrict(true), ) fixture.RunConformance(t)