bcgovimages/certbot

Certbot

注意：此仓库已弃用，不再维护。镜像现在发布于GitHub Container Registry：https://github.com/orgs/bcgov/packages/container/package/certbot

在OpenShift路由上自动更新TLS证书

要了解更多可用的公共服务，请访问https://bcgov.github.io/common-service-showcase/页面。

目录

• 摘要
• 环境变量
• 快速开始
  • 手动运行
  • 清理
• Entrust使用方法
• 提示
• 附录
  • 参考资料
  • 勘误
• 许可证

摘要

• 可使用https://letsencrypt.org/或其他ACME兼容的证书颁发机构颁发证书
• 利用并扩展https://certbot.eff.org/来管理（创建/续订）证书
• 仅应在OpenShift容器平台上执行
• 创建OpenShift CronJob，定期运行以续订TLS证书
  • CronJob将管理所有标注有标签certbot-managed=true的Route对象
  • 为所有受管主机/域颁发/续订一个证书
• 如果创建/续订证书，将新证书修补到受管的OpenShift路由

环境变量

Certbot容器镜像支持一系列环境变量来配置其行为。可通过修改定义的变量来调整Certbot行为。以下变量会改变内部Certbot应用的运行方式。

快速开始

以下提供在OpenShift中快速设置并运行Certbot作为cronjob的方法。

1. 指向OpenShift上的相应项目/命名空间

   sh
   export NAMESPACE=<YOURNAMESPACE>
   
   oc project $NAMESPACE
   

2. 确保要让Certbot管理的路由已标注标签certbot-managed=true。可使用以下命令列出符合条件的路由：

   sh
   oc get route -n $NAMESPACE -l certbot-managed=true -o=jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}'
   

3. 通过处理certbot.dc.yaml在项目/命名空间中安装Certbot，以创建CronJob及支持对象（ServiceAccount、RoleBinding、PVC等）。

   此模板接受以下参数，大致对应上述环境变量（通过oc process命令的-p参数添加）：

   参数	默认值	描述
   CERTBOT_DEBUG	false	以调试模式运行Certbot
   CERTBOT_DELETE_ACME_ROUTES	true	完成后自动清理临时ACME路由
   CERTBOT_DRYRUN	false	无执行运行
   CERTBOT_EMAIL		CSR请求发送到的***。对于Entrust，建议使用产品负责人的*@gov.bc.ca***
   CERTBOT_SERVER	https://acme-v02.api.letsencrypt.org/directory	ACME Certbot端点。对于BC Gov SSL，参见Entrust
   CERTBOT_STAGING	false	使用自签名证书续订。使用Entrust时必须设为false
   CERTBOT_SUBSET	true	如果部分域有效，允许域验证通过
   CRON_SCHEDULE	0 0 * * 1,4	Cronjob调度时间
   CRON_SUSPEND	false	暂停cronjob
   IMAGE_REGISTRY	docker.io	镜像仓库
   IMAGE_NAMESPACE	bcgovimages	镜像命名空间
   IMAGE_NAME	certbot	镜像名称
   IMAGE_TAG	latest	镜像标签。建议固定到特定版本以确保稳定性

   • 对于非生产环境，可设置CERTBOT_STAGING=true，避免达到LetsEncrypt的服务限制。
   • 默认情况下，此模板使用LetsEncrypt生成证书。如果只是测试，可使用Let's Encrypt测试端点https://acme-staging-v02.api.letsencrypt.org/directory以避免速率限制。
   • 对于生产应用，强烈建议不要使用LetsEncrypt证书。联系您的部门/机构以确定生产SSL/TLS证书管理的最佳实践。
   • 如果使用的证书提供商会在请求之外额外提供域名（如Entrust），应确保CERTBOT_SUBSET选项设为true。否则，由于额外域名未被管理，证书续订将始终失败。如果需要严格的域验证，显式将CERTBOT_SUBSET设为false。

   sh
   export CERTBOT_EMAIL=<some-valid@email.com>
   export CERTBOT_SERVER=<YOURCERTBOTSERVER>
   
   oc process -n $NAMESPACE -f "https://raw.githubusercontent.com/BCDevOps/certbot/master/openshift/certbot.dc.yaml" -p CERTBOT_EMAIL=$CERTBOT_EMAIL -p CERTBOT_SERVER=$CERTBOT_SERVER | oc apply -n $NAMESPACE -f -
   

   注意：必须提供有效的***地址！

手动运行

如需手动运行CronJob，可执行以下命令：

sh
# 创建Job
oc create job -n $NAMESPACE "certbot-manual-$(date +%s)" --from=cronjob/certbot

# 删除之前创建的手动Job
# 注意：当没有要删除的Job时，oc delete会报错
oc get job -n $NAMESPACE -o name | grep -F -e '-manual-' | xargs oc delete -n $NAMESPACE

清理

要从命名空间中移除certbot，运行以下命令。所有构建相关的清单都有build=certbot标签，所有cronjob应用相关的清单都有app=certbot标签。

sh
export NAMESPACE=<YOURNAMESPACE>

# 删除certbot.bc.yaml生成的所有清单
oc delete all -n $NAMESPACE -l build=certbot

# 删除certbot.dc.yaml生成的所有清单
oc delete cronjob,pvc,rolebinding,sa -n $NAMESPACE -l app=certbot

Entrust使用方法

Entrust是当前BC Gov生产环境唯一批准的证书提供方。从Entrust而非LetsEncrypt请求证书需要额外步骤。

1. 首先按照快速开始部分创建部署配置

2. 修改部署配置中的CERTBOT_SERVER参数以使用Entrust

   参数	默认值	描述
   CERTBOT_SERVER	https://www.entrust.net/acme/api/v1/directory/xx-xxxx-xxxx	其中xx-xxxx-xxxx是目录ID。此值可能因不同部门组织而异。请联系您的组织确定此值。

3. 确保CERTBOT_STAGING设为false。Entrust服务器没有暂存模式

4. 如果之前在同一路由上使用LetsEncrypt服务器运行过Certbot作业，需要删除现有PVC。这将移除旧的Let's Encrypt文件，下一步将创建新的PVC

5. 应用部署配置并手动运行作业或通过cron触发器运行。作业日志将显示获取证书失败，路由保持未修改状态。这是正常现象，因为证书请求仍需部门批准

6. 在CERTBOT_EMAIL***中，您会收到来自auto-notice@entrust.com的邮件，包含Tracking ID

7. 此时需要联系部门中的相应小组创建iStore订单以批准证书请求。对于NRM团队，请让产品负责人创建https://apps.nrs.gov.bc.ca/int/jira/servicedesk/customer/portal/1请求，包含以下信息：

   • 证书的域名
   • Entrust跟踪ID
   • iStore编码
   • 费用授权

8. iStore订单创建并批准后，您会收到来自auto-notice@entrust.com的另一封邮件，通知请求已批准

9. 重新运行作业，Certbot应获取证书并自动安装

提示

1. 如果首次设置自动证书续订，备份路由中的"证书"、"私钥"和"CA证书"内容

2. 列出cron作业

   sh
   export NAMESPACE=<YOURNAMESPACE>
   
   oc get -n $NAMESPACE cronjob
   

3. 描述cron作业

   sh
   export NAMESPACE=<YOURNAMESPACE>
   
   oc describe -n $NAMESPACE cronjob/certbot
   

4. 在OpenShift控制台查看cron作业：管理员视图 -> 工作负载 > 作业

5. 在OpenShift控制台访问cron作业日志，在pod列表中检查最新的已完成/失败cronjob pod（管理员视图 -> 工作负载 > Pods）

6. 如果日志中出现错误需要排查，可使用可选参数CERTBOT_DEBUG和CERTBOT_DELETE_ACME_ROUTES

   sh
   export NAMESPACE=<YOURNAMESPACE>
   export CERTBOT_SERVER=<YOURCERTBOTSERVER>
   export CERTBOT_EMAIL=<some-valid@email.com>
   
   oc process -n $NAMESPACE -f "https://raw.githubusercontent.com/BCDevOps/certbot/master/openshift/certbot.dc.yaml" -p CERTBOT_EMAIL=$EMAIL -p CERTBOT_SERVER=$CERTBOT_SERVER -p CERTBOT_STAGING=false -p CERTBOT_DEBUG=true -p CERTBOT_DELETE_ACME_ROUTES=false | oc apply -n $NAMESPACE -f -
   

   注意：排查完成后，确保手动删除ACME路由和服务，并重新部署时不使用DEBUG和DELETE_ACME_ROUTES选项！

7. 如果多次运行设置过程，确保删除所有重复的cron作业，只保留最新的。或使用以下命令删除所有certbot作业并重新开始：

   sh
   export NAMESPACE=<YOURNAMESPACE>
   
   oc get job -n $NAMESPACE -o name | grep -F -e 'certbot' | xargs oc delete
   oc get cronjob -n $NAMESPACE -o name | grep -F -e 'certbot' | xargs oc delete
   

8. 要暂停命名空间中的cronjob，可使用以下补丁命令：

   sh
   export NAMESPACE=<YOURNAMESPACE>
   
   oc patch cronjob -n $NAMESPACE certbot -p '{"spec" : {"suspend" : true }}'
   

9. 要恢复命名空间中的cronjob，可使用以下补丁命令：

   sh
   export NAMESPACE=<YOURNAMESPACE>
   
   oc patch cronjob -n $NAMESPACE certbot -p '{"spec" : {"suspend" : false }}'
   

附录

参考资料

• https://certbot.eff.org/
• https://certbot.eff.org/docs/using.html#webroot
• https://certbot.eff.org/docs/using.html#renewing-certificates
• https://letsencrypt.org/
• https://letsencrypt.org/how-it-works/
• https://github.com/certbot/certbot/issues/2697#issuecomment-242360098
• <[***]>

勘误

如果需要直接在集群上构建Certbot，可通过处理certbot.bc.yaml创建所需的构建对象。大多数情况下不再需要此操作。

此模板接受以下参数（通过oc process命令的-p参数添加）：

sh
oc process -n $NAMESPACE -f "https://raw.githubusercontent.com/BCDevOps/certbot/master/openshift/certbot.bc.yaml" | oc apply -n $NAMESPACE -f -

许可证

text
Copyright 2018 Province of British Columbia

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.