|
1 | | -# certificator |
| 1 | +# Triton Certificator |
2 | 2 |
|
3 | | -The tool that requests certificates from ACME supporting CA, solves DNS challenges, and stores certificates in Vault. |
| 3 | +This is a fork of [vinted's certificator](https://github.com/vinted/certificator) tool with customisations made to support our specific use-case, which has removed upstream features, which we have not (yet) attempted to upstream. |
4 | 4 |
|
5 | | -## Usage |
| 5 | +As such this repository has been stripped down, removing various upstream tests which are no longer valid. These can be reintroduced if they are fixed, but there's no value to keeping them while they are not. |
6 | 6 |
|
7 | | -1. Add domains that need certificates to domains.yml file |
8 | | -1. Set necessary environment variables (see [configuration](#Configuration)) |
9 | | -1. Run certificator |
10 | | -1. Find certificates in Vault |
11 | | - |
12 | | -## Configuration |
13 | | - |
14 | | -Certificator reads most configuration parameters from environment variables. |
15 | | -They are defined in [pkg/config/config.go](pkg/config/config.go) Config struct |
16 | | - |
17 | | -Configuration variables: |
18 | | -- `ACME_ACCOUNT_EMAIL` - email used in certificate retrieval process. **Required** |
19 | | -- `ACME_DNS_CHALLENGE_PROVIDER` - DNS challenge provider. Available providers can be found [here](https://go-acme.github.io/lego/dns/#dns-providers). **Required** |
20 | | -- `ACME_DNS_PROPAGATION_REQUIREMENT` - if set to true, requires complete DNS record propagation before stating that challenge is solved. Default: true |
21 | | -- `ACME_REREGISTER_ACCOUNT` - if set to true, allows registering an account with CA. This should be set to true for the first use. When credentials are stored in Vault, you can set this to false to avoid accidental registrations. Default: false |
22 | | -- `ACME_SERVER_URL` - ACME directory location. Default: https://acme-staging-v02.api.letsencrypt.org/directory |
23 | | -- `VAULT_APPROLE_ROLE_ID` - role ID for Vault approle authentication method. **Required in prod env** |
24 | | -- `VAULT_APPROLE_SECRET_ID` - secret ID for Vault approle authentication method. **Required in prod env** |
25 | | -- `VAULT_KV_STORAGE_PATH` - path in Vault KV storage where certificator stores certificates and account data. Default: secret/data/certificator/ |
26 | | -- `VAULT_ADDR` sets vault address, example: "http://localhost:8200". **Required** |
27 | | -- `LOG_FORMAT` - logging format, supported formats - JSON and LOGFMT. Default: JSON |
28 | | -- `LOG_LEVEL` - logging level, supported levels - DEBUG, INFO, WARN, ERROR, FATAL. Default: INFO. |
29 | | -- `DNS_ADDRESS` - DNS server address that is used to check challenge DNS record propagation. Default: 127.0.0.1:53 |
30 | | -- `ENVIRONMENT` - sets an environment where the certificator is running. If the environment is dev it uses token set in `VAULT_DEV_ROOT_TOKEN_ID` env variable to authenticate in Vault. If the environment is prod it uses an approle authentication method. Default: prod |
31 | | -- `CERTIFICATOR_DOMAINS_FILE` - path to a file where domains are defined. Default: /code/domains.yml |
32 | | -- `CERTIFICATOR_RENEW_BEFORE_DAYS` - set how many validity days should certificate have remaining before renewal. Default: 30 |
33 | | - |
34 | | -#### CNAME |
35 | | - |
36 | | -- `LEGO_EXPERIMENTAL_CNAME_SUPPORT` boolean value which enables CNAME support. When `true`, it tries to resolve `_acme-challenge.<YOUR_DOMAIN>` and if it finds a CNAME record for that request it solves the challenge for the CNAME record value. Example: |
37 | | - |
38 | | -``` |
39 | | -If it finds this record: |
40 | | -CNAME _acme_challenge.test.com -> test.com.challenges.test.com |
41 | | -it creates TXT record in challenges.test.com zone: |
42 | | -TXT test.com.challenges.test.com -> <CHALLENGE_VALUE> |
43 | | -CA will verify domain ownership following the same scheme |
44 | | -``` |
45 | | - |
46 | | -This allows giving this tool a token with access rights limited to a single DNS zone. |
47 | | - |
48 | | -#### Domains file |
49 | | - |
50 | | -Domains that the certificator should retrieve certificates for should be defined in this file in YAML format. An example file is in [domains.yml](domains.yml). |
51 | | - |
52 | | -Every item in the array under the `domains` key results in a certificate. The first domain in an array item is used for the CommonName field of the certificate, all other domains are added using the Subject Alternate Names extension. Domains in a single array item are separated by commas. The first domain is also used as a key in the Vault KV store. |
53 | | - |
54 | | -## Tests |
55 | | - |
56 | | -This project contains unit and integration tests. To run them follow the instructions |
57 | | - |
58 | | -#### Integration tests |
59 | | - |
60 | | -Files related to integration tests lie in directory `test`. |
61 | | -It relies on several components: pebble, vault, challtestsrv. |
62 | | - |
63 | | -Steps to run it: |
64 | | - |
65 | | -1. Build container that runs tests: |
66 | | -`docker-compose build tester` |
67 | | -1. Run tests: |
68 | | - - only integration tests: |
69 | | - `docker-compose run --rm tester go test ./test/...` |
70 | | - - all tests: |
71 | | - `docker-compose run --rm tester go test ./...` |
72 | | -1. Check results |
73 | | -1. Bring down testing infrastructure |
74 | | -`docker-compose down` |
75 | | - |
76 | | -#### Unit tests |
77 | | - |
78 | | -Unit tests can be run without any dependencies, simply execute: |
79 | | -`go test ./pkg/...` |
| 7 | +We have also added a devcontainer and a workflow for building the application container ready for use in nomad. |
0 commit comments