From 9b6be1c8dbe8e13409cb49113237299fd126cf0f Mon Sep 17 00:00:00 2001 From: Louis Taylor Date: Thu, 26 Jul 2018 17:03:02 +0100 Subject: [PATCH 1/2] Add documentation on creating DNS01 providers --- docs/devel/dns01-providers.rst | 34 ++++++++++++++++++++++++++++++++++ docs/devel/index.rst | 1 + 2 files changed, 35 insertions(+) create mode 100644 docs/devel/dns01-providers.rst diff --git a/docs/devel/dns01-providers.rst b/docs/devel/dns01-providers.rst new file mode 100644 index 000000000..e489f20bc --- /dev/null +++ b/docs/devel/dns01-providers.rst @@ -0,0 +1,34 @@ +============================ +Contributing DNS01 providers +============================ + +Steps to add a ``FooDNS`` DNS-01 provider: + +1. Create a new package under ``pkg/issuer/acme/dns/foodns``. + This is where all the code to interact with the DNS providers API will live. +2. Implement functions to match the solver interface (``Present``, ``CleanUp`` and ``Timeout``). + Use an existing provider for reference. + Most of the cert-manager providers are based off + https://github.com/xenolf/lego, so if lego supports the DNS provider you + want to add, it's fairly easy to copy it over and make modifications to fit + with the cert-manager codebase. Examples of the changes required: + + - replace uses of ``github.com/xenolf/lego/acme`` with ``github.com/jetstack/cert-manager/pkg/issuer/acme/dns/util``. + - replace uses of ``github.com/xenolf/lego/log`` with ``github.com/golang/glog``. + - remove references to ``github.com/xenolf/lego/platform/config/env``. + cert-manager does not use environment variables for internal configuration, so calls to this package should not be required. + +3. Add unit test coverage for this package. +4. Add coverage for the provider to ``pkg/issuer/acme/dns/dns_test.go``. +5. Add your provider configuration types to the API (located in ``pkg/apis/certmanager/v1alpha1/types.go``) and regenerate code (run ``./hack/update-codegen.sh``). +6. Register the provider in ``pkg/issuer/acme/dns``. +7. Add example configuration for the new provider to ``docs/reference/issuers/acme/dns01.rst``. +8. Run conformance tests for the new provider. (TODO: actually build these) +9. Submit your new provider to cert-manager, attaching the conformance test results to the pull request. + + + +Things to watch out for: + +- Assume that at any point the cert-manager process may restart. + Make sure values required for operations like ``CleanUp`` are not solely stored in memory. diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 1143e6038..928c91648 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -5,3 +5,4 @@ Development documentation :maxdepth: 1 develop-with-minikube + dns01-providers From 86ce5a7823989200ceb03a46746602bc7104a63e Mon Sep 17 00:00:00 2001 From: Louis Taylor Date: Fri, 27 Jul 2018 12:53:46 +0100 Subject: [PATCH 2/2] Add extra guidelines --- docs/devel/dns01-providers.rst | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/devel/dns01-providers.rst b/docs/devel/dns01-providers.rst index e489f20bc..5b7c53a83 100644 --- a/docs/devel/dns01-providers.rst +++ b/docs/devel/dns01-providers.rst @@ -19,14 +19,22 @@ Steps to add a ``FooDNS`` DNS-01 provider: cert-manager does not use environment variables for internal configuration, so calls to this package should not be required. 3. Add unit test coverage for this package. -4. Add coverage for the provider to ``pkg/issuer/acme/dns/dns_test.go``. -5. Add your provider configuration types to the API (located in ``pkg/apis/certmanager/v1alpha1/types.go``) and regenerate code (run ``./hack/update-codegen.sh``). -6. Register the provider in ``pkg/issuer/acme/dns``. +4. Add your provider configuration types to the API (located in ``pkg/apis/certmanager/v1alpha1/types.go``) and regenerate code (run ``./hack/update-codegen.sh``). + New API types should have an associated short documentation string, + which is added to the reference API documentation (run ``./hack/update-reference-docs-dockerized.sh`` to update the API documentation). +5. Register the provider in ``pkg/issuer/acme/dns``: + + - The constructor for the provider needs adding to ``dnsProviderConstructors``, + - ``solverForIssuerProvider`` must be updated to handle retrieving any information for the new provider (for example, fetching credentials from a secret) + and constructing a new instance of the provider. + +6. Add coverage for the provider to ``pkg/issuer/acme/dns/dns_test.go``. 7. Add example configuration for the new provider to ``docs/reference/issuers/acme/dns01.rst``. -8. Run conformance tests for the new provider. (TODO: actually build these) -9. Submit your new provider to cert-manager, attaching the conformance test results to the pull request. - - + The more information here the better, + this example and corresponding documentation should inform users how to use and configure this backend, + as well as mentioning any nuances with using this particular provider. +8. Test your provider out against a real account, and make sure you can issue a Certificate. +9. Submit your new provider to cert-manager! Things to watch out for: