Skip to content

Commit e907cff

Browse files
jujagajujaga
committed
Mass update readme documentation
This commit focuses on updating, standardizing and ordering all parameters related to deploying and managing Certbot. By ensuring that all parameters use the same naming scheme, it will reduce confusion on intent. As well, we have changed the default cronjob schedule to run bi-weekly on Monday and Thursday as opposed to running every 12 hours. Since certificates tend to last a while, running it more frequently than twice a week is a waste of cluster resources. Signed-off-by: Jeremy Ho <jujaga@gmail.com>
1 parent 1178490 commit e907cff

4 files changed

Lines changed: 374 additions & 253 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -1,219 +1,44 @@
1-
# Certbot [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
1+
# Certbot [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Lifecycle:Stable](https://img.shields.io/badge/Lifecycle-Stable-97ca00)](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md)
22

3-
Automatically update TLS Certificates on OpenShift Routes
4-
5-
- [Assumptions](#assumptions)
6-
- [Solution](#solution)
7-
- [Installation](#installation)
8-
- [Manual Run](#manual-run)
9-
- [Cleanup](#cleanup)
10-
- [Entrust Usage](#entrust-usage)
11-
- [Tips](#tips)
12-
- [References](#references)
13-
- [License](#license)
14-
15-
## Assumptions
16-
17-
- Using <https://letsencrypt.org/> for issuing certificates
18-
- Using <https://certbot.eff.org/> for managing (create/renew) certificates
19-
- Run inside OpenShift
20-
21-
## Solution
22-
23-
- Create a OpenShift `CronJob` which will run on a regular schedule for renewing TLS certificate if required.
24-
- The `CronJob` will manage a set of required `Service` and `Route`s objects.
25-
- The `CronJob` manages certificates of all routes with a label `certbot-managed=true`
26-
- One certificate will be issued/renewed for all the managed hosts/domains.
27-
- If a cert is created/renewed, apply the new certificate to the related routes
28-
29-
## Installation
30-
31-
1. Point to the appropriate namespace (usually tools)
32-
33-
``` sh
34-
export NAMESPACE=<YOURNAMESPACE>
35-
36-
oc project $NAMESPACE
37-
```
38-
39-
1. Install `certbot.bc.yaml` to create the required build objects.
40-
_Note: If the build fails, make sure your namespace contains an NSP allowing '@app:k8s:serviceaccountname=builder' (OCP builders) to access 'ext:network=any' (egress internet)_
41-
42-
This template accepts the following parameters (add with -p to the `oc process` command):
43-
44-
| Parameter | Default Value | Description |
45-
| --- | --- | --- |
46-
| `GIT_REF` | `master` | Git Pull Request or Branch Reference (i.e. 'pull/CHANGE_ID/head') |
47-
| `GIT_URL` | `https://github.com/BCDevOps/certbot.git` | Git Repository URL |
48-
49-
``` sh
50-
oc process -n $NAMESPACE -f "https://raw.githubusercontent.com/BCDevOps/certbot/master/openshift/certbot.bc.yaml" | oc apply -n $NAMESPACE -f -
51-
```
3+
[![version](https://img.shields.io/docker/v/bcgovimages/certbot.svg?sort=semver)](https://hub.docker.com/r/bcgovimages/certbot)
4+
[![pulls](https://img.shields.io/docker/pulls/bcgovimages/certbot.svg)](https://hub.docker.com/r/bcgovimages/certbot)
5+
[![size](https://img.shields.io/docker/image-size/bcgovimages/certbot.svg)](https://hub.docker.com/r/bcgovimages/certbot)
526

53-
1. Install `certbot.dc.yaml` to create the CronJob and supporting objects (NSP, ServiceAccount, RoleBinding, PVC, etc).
54-
This template accepts the following parameters (add with -p to the `oc process` command):
55-
56-
| Parameter | Default Value | Description |
57-
| --- | --- | --- |
58-
| `CERTBOT_CRON_SCHEDULE` | `0 */12 * * *` | Cronjob Schedule |
59-
| `CERTBOT_STAGING` | `false` (must be `false` for [Entrust](#entrust-usage)) | Self-signed cert renewals |
60-
| `CERTBOT_SUSPEND_CRON` | `false` | Suspend cronjob |
61-
| `CERTBOT_SERVER` | `https://acme-v02.api.letsencrypt.org/directory` (for BC Gov SSL, see [Entrust](#entrust-usage)) | ACME Certbot endpoint |
62-
| `DRYRUN` | `false` | Run without executing |
63-
| `DEBUG` | `false` | Debug mode |
64-
| `DELETE_ACME_ROUTES` | `true` | Self cleanup temporary ACME routes when done |
65-
| `SUBSET` | `true` | Allow domain validation to pass if a subset of them are valid |
66-
| `EMAIL` | For [Entrust](#entrust-usage), Product Owner's `@gov.bc.ca` is suggested | Email where CSR requests are sent to |
67-
| `NAMESPACE` | | Openshift Namespace |
68-
| `IMAGE_REGISTRY` | `image-registry.openshift-image-registry.svc:5000` | Openshift Image Registry |
69-
| `SOURCE_IMAGE_NAME` | `certbot` | Image Name |
70-
| `TAG_NAME` | `latest` | Image Tag |
71-
72-
- For non-prod environments, you may set `CERTBOT_STAGING=true`, so you don't hit any service limits at Let's Encrypt.
73-
- By default, this template will use Let's Encrypt for certificate generation. If you are just testing, you may use Let's Encrypt testing endpoint `https://acme-staging-v02.api.letsencrypt.org/directory` to avoid being rate limited.
74-
- For your production applications, we strongly recommend **NOT** using Let's Encrypt certificates. Contact your ministry/department to determine best practices for production SSL/TLS certificate management.
75-
- If you are using a certificate provider that gives you extra domains on top of what you have requested (like Entrust), you should make sure that the `SUBSET` option is set to true. Otherwise certificate renewals will always fail because their extra domain will never be managed on our end and choke. If you require stringent domain validation, set `SUBSET` to false explicitly.
76-
77-
``` sh
78-
export CERTBOT_SERVER=<YOURCERTBOTSERVER>
79-
export EMAIL=<some-valid@email.com>
80-
81-
oc process -n $NAMESPACE -f "https://raw.githubusercontent.com/BCDevOps/certbot/master/openshift/certbot.dc.yaml" -p EMAIL=$EMAIL -p NAMESPACE=$NAMESPACE -p CERTBOT_SERVER=$CERTBOT_SERVER | oc apply -n $NAMESPACE -f -
82-
```
83-
84-
_PS: You MUST supply a valid email address!_
85-
86-
To include this cronjob in your pipeline, it is recommended that you copy `certbot.bc.yaml` and `certbot.dc.yaml` to your appliciton project. The build config will point back to this repo to include the latest changes to the contents of the docker folder. _Note: If you are using BCDK, there is a bug in it that requires you to have a "docker" folder in your repo._
87-
88-
## Manual Run
89-
90-
If you need to run the CronJob manually, you can do that by running:
91-
92-
``` sh
93-
# Delete any previous manual Jobs created
94-
# Note: When there are no jobs to delete, you will get an error for oc delete.
95-
oc get job -n $NAMESPACE -o name | grep -F -e '-manual-' | xargs oc delete -n $NAMESPACE
96-
97-
# Create a Job
98-
oc create job -n $NAMESPACE "certbot-manual-$(date +%s)" --from=cronjob/certbot
99-
```
100-
101-
## Cleanup
102-
103-
To remove certbot from your namespace, run the following commands. All build related manifests will have a `build=certbot` label, and all cronjob application related manifests will have an `app=certbot` label.
7+
Automatically update TLS Certificates on OpenShift Routes
1048

105-
``` sh
106-
export NAMESPACE=<YOURNAMESPACE>
9+
To learn more about the **Common Services** available visit the [Common Services Showcase](https://bcgov.github.io/common-service-showcase/) page.
10710

108-
# Delete all manifests generated by certbot.dc.yaml
109-
oc delete cronjob,pvc,rolebinding,sa -n $NAMESPACE --selector app=certbot
11+
## Directory Structure
11012

111-
# Delete all manifests generated by certbot.dc.yaml
112-
oc delete all -n $NAMESPACE --selector build=certbot
13+
```txt
14+
.github/ - PR and Issue templates
15+
docker/ - Certbot application Root
16+
openshift/ - OpenShift-deployment files
17+
CODE-OF-CONDUCT.md - Code of Conduct
18+
COMPLIANCE.yaml - BCGov PIA/STRA compliance status
19+
CONTRIBUTING.md - Contributing Guidelines
20+
LICENSE - License
21+
SECURITY.md - Security Policy and Reporting
11322
```
11423

115-
## Entrust Usage
116-
117-
Entrust is the only approved certificate provider for BC Gov production environments currently. There are a few extra steps required to request certificates from Entrust instead of Let's Encrypt.
118-
119-
1. Start by creating the deployment config found in the [Installation](#installation) section
120-
121-
1. Modify the `CERTBOT_SERVER` parameter in the deployment config to use Entrust
122-
123-
| Parameter | Default Value | Description |
124-
| --- | --- | --- |
125-
| `CERTBOT_SERVER` | `https://www.entrust.net/acme/api/v1/directory/xx-xxxx-xxxx` | Where `xx-xxxx-xxxx` is the directory ID. This value may vary between different ministry organizations. Please contact your organization to determine this value. |
126-
127-
1. Make sure `CERTBOT_STAGING` is set to `false`. The Entrust server does not have a staging mode
128-
129-
1. If the Certbot job was previously ran on the same route using Let's Encrypt server then you will need to delete the existing PVC. This will remove old Let's Encrypt files and a new PVC will be created on the next step
130-
131-
1. Apply the deployment config and run the job manually or by cron trigger. The job logs will display it has failed to obtain the certificates and the route will remain unmodified. This is normal because the request still needs to be approved by your ministry first
132-
133-
1. In the `EMAIL` inbox you should receive an email from `auto-notice@entrust.com` containing a `Tracking ID`.
134-
135-
1. At this point you need the appropriate group in your ministry to create an iStore order to approve the certificate request. For NRM teams, please have your PO create a [Service Desk](https://apps.nrs.gov.bc.ca/int/jira/servicedesk/customer/portal/1) request containing the following information.
136-
- Domain for the certificate
137-
- Entrust Tracking ID
138-
- iStore Coding
139-
- Expense Authority
140-
- [Example Service Desk Ticket](https://apps.nrs.gov.bc.ca/int/jira/servicedesk/customer/portal/1/SD-26581)
141-
142-
1. Once the iStore order has been created you should receive another email from `auto-notice@entrust.com` letting you know the request has been approved
143-
144-
1. Re-run the job and Certbot should obtain the certificates and install them successfully
145-
146-
## Tips
147-
148-
1. If you are going to setup automatic cert renewals for the first time, backup "Certficate", "Private Key" and "CA Certificate" contents from your route.
149-
1. List your cron jobs
150-
151-
``` sh
152-
export NAMESPACE=<YOURNAMESPACE>
153-
154-
oc get -n $NAMESPACE cronjob
155-
```
156-
157-
1. To describe your cron job
158-
159-
``` sh
160-
export NAMESPACE=<YOURNAMESPACE>
161-
162-
oc describe -n $NAMESPACE cronjob/certbot
163-
```
164-
165-
1. To see your cron jobs in Openshift GUI: Resources > Other Resources > Job
166-
1. To access the logs for cron jobs in Openshift GUI: Monitoring > Uncheck "Hide older resources". You will see recently terminated certbot that would have terminated based on your schedule.
167-
1. If you are seeing errors in the logs and need to troubleshoot, you can use optional parameters DEBUG and DELETE_ACME_ROUTES.
168-
169-
``` sh
170-
export CERTBOT_SERVER=<YOURCERTBOTSERVER>
171-
export EMAIL=<some-valid@email.com>
172-
export NAMESPACE=<YOURNAMESPACE>
173-
174-
oc process -n $NAMESPACE -f "https://raw.githubusercontent.com/BCDevOps/certbot/master/openshift/certbot.dc.yaml" -p EMAIL=$EMAIL -p NAMESPACE=$NAMESPACE -p CERTBOT_SERVER=$CERTBOT_SERVER -p CERTBOT_STAGING=false -p DEBUG=true -p DELETE_ACME_ROUTES=false | oc apply -n $NAMESPACE -f -
175-
```
176-
177-
_PS: Ensure that you manually delete the ACME Route and Service after you are done troubleshooting and redeploy without the DEBUG and DELETE_ACME_ROUTES options!_
178-
179-
1. If you end up running the setup process multiple times, ensure that you have deleted all the duplicate copies of those cron jobs and only keep the latest one. Or to delete all the certbot jobs and start fresh you can use the below.
180-
181-
``` sh
182-
export NAMESPACE=<YOURNAMESPACE>
183-
184-
oc get job -n $NAMESPACE -o name | grep -F -e 'certbot' | xargs oc delete
185-
oc get cronjob -n $NAMESPACE -o name | grep -F -e 'certbot' | xargs oc delete
186-
```
187-
188-
1. To suspend a cronjob in your namespace, you can use the below patch command.
189-
190-
``` sh
191-
export NAMESPACE=<YOURNAMESPACE>
24+
## Documentation
19225

193-
oc patch cronjob -n $NAMESPACE certbot -p '{"spec" : {"suspend" : false }}'
194-
```
26+
* [Docker Readme](docker/README.md)
27+
* [Security Reporting](SECURITY.md)
19528

196-
1. To resume a cronjob in your namespace, you can use the below patch command.
29+
## Getting Help or Reporting an Issue
19730

198-
``` sh
199-
export NAMESPACE=<YOURNAMESPACE>
31+
To report bugs/issues/features requests, please file an [issue](https://github.com/BCDevOps/certbot/issues).
20032

201-
oc patch cronjob -n $NAMESPACE certbot -p '{"spec" : {"suspend" : true }}'
202-
```
33+
## How to Contribute
20334

204-
## References
35+
If you would like to contribute, please see our [contributing](CONTRIBUTING.md) guidelines.
20536

206-
- <https://certbot.eff.org/docs/using.html#webroot>
207-
- <https://certbot.eff.org/docs/using.html#renewing-certificates>
208-
- <https://letsencrypt.org/>
209-
- <https://letsencrypt.org/how-it-works/>
210-
- <https://certbot.eff.org/>
211-
- <https://github.com/certbot/certbot/issues/2697#issuecomment-242360098>
212-
- <https://www.entrust.net/knowledge-base/technote.cfm?tn=70882>
37+
Please note that this project is released with a [Contributor Code of Conduct](CODE-OF-CONDUCT.md). By participating in this project you agree to abide by its terms.
21338

21439
## License
21540

216-
``` text
41+
```txt
21742
Copyright 2018 Province of British Columbia
21843
21944
Licensed under the Apache License, Version 2.0 (the "License");

0 commit comments

Comments
 (0)