diff options
Diffstat (limited to 'roles/openshift_certificate_expiry/README.md')
| -rw-r--r-- | roles/openshift_certificate_expiry/README.md | 312 |
1 files changed, 220 insertions, 92 deletions
diff --git a/roles/openshift_certificate_expiry/README.md b/roles/openshift_certificate_expiry/README.md index a88470bdd..8f71b94ff 100644 --- a/roles/openshift_certificate_expiry/README.md +++ b/roles/openshift_certificate_expiry/README.md @@ -1,5 +1,4 @@ -OpenShift Certificate Expiration Checker -======================================== +# OpenShift Certificate Expiration Checker OpenShift certificate expiration checking. Be warned of certificates expiring within a configurable window of days, and notified of @@ -21,8 +20,7 @@ cluster. For best results run `ansible-playbook` with the `-v` option. -Role Variables --------------- +# Role Variables Core variables in this role: @@ -42,8 +40,64 @@ Optional report/result saving variables in this role: | `openshift_certificate_expiry_json_results_path` | `/tmp/cert-expiry-report.json` | The full path to save the json report as | -Example Playbook ----------------- +# Using this Role + +How to use the Certificate Expiration Checking Role. + +> **NOTE:** In the examples shown below, ensure you change **HOSTS** +> to the path of your inventory file. + +## Run with ansible-playbook + +Run one of the example playbooks using an inventory file +representative of your existing cluster. Some example playbooks are +included in this repo, or you can read on below after this example to +craft you own. + +``` +$ ansible-playbook -v -i HOSTS ./roles/openshift_certificate_expiry/examples/playbooks/easy-mode.yaml +``` + +Using the `easy-mode.yaml` playbook will produce: + +* Reports including healthy and unhealthy hosts +* A JSON report in `/tmp/` +* A stylized HTML report in `/tmp/` + + +## More Example Playbooks + +> **Note:** These Playbooks are available to run directly out of the +> [examples/playbooks/](examples/playbooks/) directory. + + +This example playbook is great if you're just wanting to **try the +role out**. This playbook enables HTML and JSON reports. The warning +window is set very large so you will almost always get results back. +All certificates (healthy or not) are included in the results: + +```yaml +--- +- name: Check cert expirys + hosts: nodes:masters:etcd + become: yes + gather_facts: no + vars: + openshift_certificate_expiry_warning_days: 1500 + openshift_certificate_expiry_save_json_results: yes + openshift_certificate_expiry_generate_html_report: yes + openshift_certificate_expiry_show_all: yes + roles: + - role: openshift_certificate_expiry +``` + +``` +$ ansible-playbook -v -i HOSTS ./roles/openshift_certificate_expiry/examples/playbooks/easy-mode.yaml +``` + +> [View This Playbook](examples/playbooks/easy-mode.yaml) + +*** Default behavior: @@ -57,6 +111,16 @@ Default behavior: - role: openshift_certificate_expiry ``` +``` +$ ansible-playbook -v -i HOSTS ./roles/openshift_certificate_expiry/examples/playbooks/default.yaml +``` + + +> [View This Playbook](examples/playbooks/default.yaml) + +*** + + Generate HTML and JSON artifacts in their default paths: ```yaml @@ -72,6 +136,15 @@ Generate HTML and JSON artifacts in their default paths: - role: openshift_certificate_expiry ``` +``` +$ ansible-playbook -v -i HOSTS ./roles/openshift_certificate_expiry/examples/playbooks/html_and_json_default_paths.yaml +``` + + +> [View This Playbook](examples/playbooks/html_and_json_default_paths.yaml) + +*** + Change the expiration warning window to 1500 days (good for testing the module out): @@ -87,6 +160,15 @@ the module out): - role: openshift_certificate_expiry ``` +``` +$ ansible-playbook -v -i HOSTS ./roles/openshift_certificate_expiry/examples/playbooks/longer_warning_period.yaml +``` + + +> [View This Playbook](examples/playbooks/longer_warning_period.yaml) + +*** + Change the expiration warning window to 1500 days (good for testing the module out) and save the results as a JSON file: @@ -103,9 +185,31 @@ the module out) and save the results as a JSON file: - role: openshift_certificate_expiry ``` +``` +$ ansible-playbook -v -i HOSTS ./roles/openshift_certificate_expiry/examples/playbooks/longer-warning-period-json-results.yaml +``` + + +> [View This Playbook](examples/playbooks/longer-warning-period-json-results.yaml) + -JSON Output ------------ + +# Output Formats + +As noted above there are two ways to format your check report. In +`json` format for machine parsing, or as a stylized `html` page for +easy skimming. These options are shown below. + +## HTML Report + + + +For an example of the HTML report you can browse, save +[examples/cert-expiry-report.html](examples/cert-expiry-report.html) +and then open the file in your browser. + + +## JSON Report There are two top-level keys in the saved JSON results, `data` and `summary`. @@ -122,85 +226,116 @@ certificates: * expiring within the configured warning window * already expired -The example below is abbreviated to save space: +For an example of the full JSON report, see [examples/cert-expiry-report.json](examples/cert-expiry-report.json). + +The example below is abbreviated to save space. ```json { - "data": { - "192.168.124.148": { - "etcd": [ - { - "cert_cn": "CN:etcd-signer@1474563722", - "days_remaining": 350, - "expiry": "2017-09-22 17:02:25", - "health": "warning", - "path": "/etc/etcd/ca.crt" - }, - ], - "kubeconfigs": [ - { - "cert_cn": "O:system:nodes, CN:system:node:m01.example.com", - "days_remaining": 715, - "expiry": "2018-09-22 17:08:57", - "health": "warning", - "path": "/etc/origin/node/system:node:m01.example.com.kubeconfig" - }, - { - "cert_cn": "O:system:cluster-admins, CN:system:admin", - "days_remaining": 715, - "expiry": "2018-09-22 17:04:40", - "health": "warning", - "path": "/etc/origin/master/admin.kubeconfig" - } - ], - "meta": { - "checked_at_time": "2016-10-07 15:26:47.608192", - "show_all": "True", - "warn_before_date": "2020-11-15 15:26:47.608192", - "warning_days": 1500 - }, - "ocp_certs": [ - { - "cert_cn": "CN:172.30.0.1, DNS:kubernetes, DNS:kubernetes.default, DNS:kubernetes.default.svc, DNS:kubernetes.default.svc.cluster.local, DNS:m01.example.com, DNS:openshift, DNS:openshift.default, DNS:openshift.default.svc, DNS:openshift.default.svc.cluster.local, DNS:172.30.0.1, DNS:192.168.124.148, IP Address:172.30.0.1, IP Address:192.168.124.148", - "days_remaining": 715, - "expiry": "2018-09-22 17:04:39", - "health": "warning", - "path": "/etc/origin/master/master.server.crt" - }, - { - "cert_cn": "CN:openshift-signer@1474563878", - "days_remaining": 1810, - "expiry": "2021-09-21 17:04:38", - "health": "ok", - "path": "/etc/origin/node/ca.crt" - } - ], - "registry": [ - { - "cert_cn": "CN:172.30.101.81, DNS:docker-registry-default.router.default.svc.cluster.local, DNS:docker-registry.default.svc.cluster.local, DNS:172.30.101.81, IP Address:172.30.101.81", - "days_remaining": 728, - "expiry": "2018-10-05 18:54:29", - "health": "warning", - "path": "/api/v1/namespaces/default/secrets/registry-certificates" - } - ], - "router": [ - { - "cert_cn": "CN:router.default.svc, DNS:router.default.svc, DNS:router.default.svc.cluster.local", - "days_remaining": 715, - "expiry": "2018-09-22 17:48:23", - "health": "warning", - "path": "/api/v1/namespaces/default/secrets/router-certs" - } - ] + "data": { + "m01.example.com": { + "etcd": [ + { + "cert_cn": "CN:172.30.0.1, DNS:kubernetes, DNS:kubernetes.default, DNS:kubernetes.default.svc,...", + "days_remaining": 722, + "expiry": "2019-01-09 17:00:03", + "health": "warning", + "path": "/etc/origin/master/etcd.server.crt", + "serial": 7, + "serial_hex": "0x7" + } + ], + "kubeconfigs": [ + { + "cert_cn": "O:system:nodes, CN:system:node:m01.example.com", + "days_remaining": 722, + "expiry": "2019-01-09 17:03:28", + "health": "warning", + "path": "/etc/origin/node/system:node:m01.example.com.kubeconfig", + "serial": 11, + "serial_hex": "0xb" } + ], + "meta": { + "checked_at_time": "2017-01-17 10:36:25.230920", + "show_all": "True", + "warn_before_date": "2021-02-25 10:36:25.230920", + "warning_days": 1500 + }, + "ocp_certs": [ + { + "cert_cn": "CN:172.30.0.1, DNS:kubernetes, DNS:kubernetes.default, DNS:kubernetes.default.svc,...", + "days_remaining": 722, + "expiry": "2019-01-09 17:00:02", + "health": "warning", + "path": "/etc/origin/master/master.server.crt", + "serial": 4, + "serial_hex": "0x4" + } + ], + "registry": [ + { + "cert_cn": "CN:172.30.242.251, DNS:docker-registry-default.router.default.svc.cluster.local,...", + "days_remaining": 722, + "expiry": "2019-01-09 17:05:54", + "health": "warning", + "path": "/api/v1/namespaces/default/secrets/registry-certificates", + "serial": 13, + "serial_hex": "0xd" + } + ], + "router": [ + { + "cert_cn": "CN:router.default.svc, DNS:router.default.svc, DNS:router.default.svc.cluster.local", + "days_remaining": 722, + "expiry": "2019-01-09 17:05:46", + "health": "warning", + "path": "/api/v1/namespaces/default/secrets/router-certs", + "serial": 5050662940948454653, + "serial_hex": "0x46178f2f6b765cfd" + } + ] }, - "summary": { - "warning": 6, - "expired": 0, - "total": 7, - "ok": 1 + "n01.example.com": { + "etcd": [], + "kubeconfigs": [ + { + "cert_cn": "O:system:nodes, CN:system:node:n01.example.com", + "days_remaining": 722, + "expiry": "2019-01-09 17:03:28", + "health": "warning", + "path": "/etc/origin/node/system:node:n01.example.com.kubeconfig", + "serial": 11, + "serial_hex": "0xb" + } + ], + "meta": { + "checked_at_time": "2017-01-17 10:36:25.217103", + "show_all": "True", + "warn_before_date": "2021-02-25 10:36:25.217103", + "warning_days": 1500 + }, + "ocp_certs": [ + { + "cert_cn": "CN:192.168.124.11, DNS:n01.example.com, DNS:192.168.124.11, IP Address:192.168.124.11", + "days_remaining": 722, + "expiry": "2019-01-09 17:03:29", + "health": "warning", + "path": "/etc/origin/node/server.crt", + "serial": 12, + "serial_hex": "0xc" + } + ], + "registry": [], + "router": [] } + }, + "summary": { + "expired": 0, + "ok": 3, + "total": 15, + "warning": 12 + } } ``` @@ -233,24 +368,17 @@ $ jq '.summary.warning,.summary.expired' /tmp/cert-expiry-report.json ``` -Requirements ------------- - +# Requirements * None -Dependencies ------------- - +# Dependencies * None -License -------- - +# License Apache License, Version 2.0 -Author Information ------------------- +# Author Information Tim Bielawa (tbielawa@redhat.com) |