This a helm chart for obtaining and automatically renewing TLS certificate on the NERSC spin platform.
This helm chart automates the steps described in the repository dingpf/acme.
Before installation, you will need:
kubectl
and helm
;kubeconfig
from the Spin cluster where your project runs (either the "development" or "production" cluster).kubectl
For up-to-date information, please refer to the official documentation.
kubectl
via curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl
;kubectl
to be executable (chmod +x kubectl
);kubectl
to its desired destination (e.g. mv kubectl $HOME/bin/kubectl
);kubectl
should be include in your PATH
environment variable, add it if needed (e.g. export PATH=$HOME/bin:$PATH
)helm
For up-to-date information, please refer to the official documentation.
tar -zxvf helm-v3.0.0-linux-amd64.tar.gz
)mv linux-amd64/helm $HOME/bin/helm
);helm
should be include in your PATH
environment variable, add it if needed (e.g. export PATH=$HOME/bin:$PATH
)KUBECONFIG
KUBECONFIG is a YAML file containing the deteails of the k8s cluster, such as its address, and your own authentication credentials. It can be downloaded from the Spin.
$HOME/.kube
directory if not existing, and save the downloaded file to $HOME/.kube/config
; alternatively, you can set the KUBECONFIG
environment variable to the path to the downloaded YAML file.KUBECONFIG
secretUsing kubectl
, create a kubeconfig
secret in the targeted namespace (replace <targeted_namespace>
and <path to kubeconfig>
accordingly):
kubectl -n <targeted_namespace> create secret generic kubeconfig --from-file=kubeconfig=<path to kubeconfig>
This helm chart takes consideration of two different usage cases. The installation procedure is different.
In this case, the following conditions must be met:
<ingress>.<namespace>.<cluster>.svc.spin.nersc.gov
. Clone this repository with git clone https://github.com/dingp/spin-acme.git
.
The directory tree looks like the following:
spin-acme
├── charts
├── Chart.yaml
├── README.md
├── templates
│ ├── certsecret.yaml
│ ├── cronjob.yaml
│ ├── _helpers.tpl
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── webpvc.yaml
│ └── websrv.yaml
└── values.yaml
2 directories, 10 files
Make a copy of values.yaml
, and modify it by setting:
<uid>
<gid>
<domain>
<email>
<port>
<ingress_name>
<cluster>
(can be development.svc.spin.nersc.org
or production.svc.spin.nersc.org
)existing-websrv
pvc-existing-webroot
webServer.existing
field from false
to true
Install the helm chart with the following command. Replace <namespace>
with your namespace. acmecron
is a release name for which you can name your own.
helm install -n <namespace> -f modified-values.yaml acmecron ./spin-acme
The results of this installation are:
tls-cert
;Once the chart is installed, you can trigger the cronjob manually once to request and use the initial certificate. To trigger the cronjob, you can use the webUI, select "Workloads" -> "CronJobs", click the three dots beside the cronjob, and choose "Run Now".
Alternatively, you can trigger the CronJob via kubectl
.
# get the cronjob name
kubectl get cronjob -n <namespace>
# replace cronjob_name, and job_name below
kubectl create job --from=cronjob/<cronjob_name> <job_name>
It is recommended to "View Logs" while the triggered job is running, and verify the procedure is completed successfully.
This case requires the followings conditions to be met:
myingress
;myingress.mynamespace.development.svc.spin.nersc.gov
. This is applicatable to the usage cases like:
Similar as Case 1 above, but change the following in the copied values.yaml
:
<uid>
<gid>
<domain>
<email>
<port>
to 8080
<ingress_name>
<cluster>
(can be development.svc.spin.nersc.org
or production.svc.spin.nersc.org
)Different than Case 1, this installation of the chart will result in:
Follow instructions in Case 1 to trigger the initial run of the cronjob, view logs while it's running, and verify the initial request is completed successfully. Same as in Case 1, once the TLS certificate is obtained, it will replace original self-generated certificate.
At this point, you will need to modify the ingress to point it to your API server, or your existing web server (for which we didn't have write access to its webroot).
During, the future cronjob runs, your modified ingress will be saved first, changed briefly to the simple web server's port 8080, restored back once the certificate is renewed.
If you made changes to values.yml
, you can upgrade
the installed chart by:
helm upgrade -n <namespace> -f modified-values.yaml <release-name> ./spin-acme
Note the <release-name>
should be the same one you used during initial installation. In the Case 2, if you've made modifications to the ingress after the initial Cronjob run, the modifications will be lost after upgrade, and will need to be re-applied. It's recommended that you backup the YAML for the ingress before the upgrade.
In case you want to uninstall the chart, you can do so by:
helm uninstall --namespace <namespace> <release-name>
Similarly, the <release-name>
should be the same one you used during initial installation.
After the uninstallation, the ingress, cronjob, web server, PVC etc will all be removed from the namespace, except the TLS secret.
You can make a 30-minute appointment during NERSC's weekly Spin office hours for assistance with setting up TLS certificate issuing/renewing for your workload.