diff options
Diffstat (limited to 'examples')
| -rw-r--r-- | examples/README.md | 93 | ||||
| -rw-r--r-- | examples/certificate-check-upload.yaml | 53 | ||||
| -rw-r--r-- | examples/certificate-check-volume.yaml | 60 | ||||
| -rw-r--r-- | examples/scheduled-certcheck-upload.yaml | 53 | ||||
| -rw-r--r-- | examples/scheduled-certcheck-volume.yaml | 58 |
5 files changed, 317 insertions, 0 deletions
diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..d54752fb9 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,93 @@ +# openshift-ansible usage examples + +The primary use of `openshift-ansible` is to install, configure and upgrade OpenShift clusters. + +This is typically done by direct invocation of Ansible tools like `ansible-playbook`. This use case is covered in detail in the [OpenShift advanced installation documentation](https://docs.openshift.org/latest/install_config/install/advanced_install.html) + +For OpenShift Container Platform there's also an installation utility that wraps `openshift-ansible`. This usage case is covered in the [Quick Installation](https://docs.openshift.com/container-platform/latest/install_config/install/quick_install.html) section of the documentation. + +The usage examples below cover use cases other than install/configure/upgrade. + +## Container image + +The examples below run [openshift-ansible in a container](../README_CONTAINER_IMAGE.md) to perform certificate expiration checks on an OpenShift cluster from pods running on the cluster itself. + +You can find more details about the certificate expiration check roles and example playbooks in [the openshift_certificate_expiry role's README](../roles/openshift_certificate_expiry/README.md). + +### Job to upload certificate expiration reports + +The example `Job` in [certificate-check-upload.yaml](certificate-check-upload.yaml) executes a [Job](https://docs.openshift.org/latest/dev_guide/jobs.html) that checks the expiration dates of the internal certificates of the cluster and uploads HTML and JSON reports to `/etc/origin/certificate_expiration_report` in the masters. + +This example uses the [`easy-mode-upload.yaml`](../playbooks/certificate_expiry/easy-mode-upload.yaml) example playbook, which generates reports and uploads them to the masters. The playbook can be customized via environment variables to control the length of the warning period (`CERT_EXPIRY_WARN_DAYS`) and the location in the masters where the reports are uploaded (`COPY_TO_PATH`). + +The job expects the inventory to be provided via the *hosts* key of a [ConfigMap](https://docs.openshift.org/latest/dev_guide/configmaps.html) named *inventory*, and the passwordless ssh key that allows connecting to the hosts to be availalbe as *ssh-privatekey* from a [Secret](https://docs.openshift.org/latest/dev_guide/secrets.html) named *sshkey*, so these are created first: + + oc new-project certcheck + oc create configmap inventory --from-file=hosts=/etc/ansible/hosts + oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa + +Note that `inventory`, `hosts`, `sshkey` and `ssh-privatekey` are referenced by name from the provided example Job definition. If you use different names for the objects/attributes you will have to adjust the Job accordingly. + +To create the Job: + + oc create -f examples/certificate-check-upload.yaml + +### Scheduled job for certificate expiration report upload + +**Note**: This example uses the [ScheduledJob](https://docs.openshift.com/container-platform/3.4/dev_guide/scheduled_jobs.html) object, which has been renamed to [CronJob](https://docs.openshift.org/latest/dev_guide/cron_jobs.html) upstream and is still a Technology Preview subject to further change. + +The example `ScheduledJob` in [scheduled-certcheck-upload.yaml](scheduled-certcheck-upload.yaml) does the same as the `Job` example above, but it is scheduled to automatically run every first day of the month (see the `spec.schedule` value in the example). + +The job definition is the same and it expects the same configuration: we provide the inventory and ssh key via a ConfigMap and a Secret respectively: + + oc new-project certcheck + oc create configmap inventory --from-file=hosts=/etc/ansible/hosts + oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa + +And then we create the ScheduledJob: + + oc create -f examples/scheduled-certcheck-upload.yaml + +### Job and ScheduledJob to check certificates using volumes + +There are two additional examples: + + - A `Job` [certificate-check-volume.yaml](certificate-check-volume.yaml) + - A `ScheduledJob` [scheduled-certcheck-upload.yaml](scheduled-certcheck-upload.yaml) + +These perform the same work as the two examples above, but instead of uploading the generated reports to the masters they store them in a custom path within the container that is expected to be backed by a [PersistentVolumeClaim](https://docs.openshift.org/latest/dev_guide/persistent_volumes.html), so that the reports are actually written to storage external to the container. + +These examples assume that there is an existing `PersistentVolumeClaim` called `certcheck-reports` and they use the [`html_and_json_timestamp.yaml`](../playbooks/certificate_expiry/html_and_json_timestamp.yaml) example playbook to write timestamped reports into it. + +You can later access the reports from another pod that mounts the same volume, or externally via direct access to the backend storage behind the matching `PersistentVolume`. + +To run these examples we prepare the inventory and ssh keys as in the other examples: + + oc new-project certcheck + oc create configmap inventory --from-file=hosts=/etc/ansible/hosts + oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa + +Additionally we allocate a `PersistentVolumeClaim` to store the reports: + + oc create -f - <<PVC + --- + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: certcheck-reports + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + PVC + +With that we can run the `Job` once: + + oc create -f examples/certificate-check-volume.yaml + +or schedule it to run periodically as a `ScheduledJob`: + + oc create -f examples/scheduled-certcheck-volume.yaml + diff --git a/examples/certificate-check-upload.yaml b/examples/certificate-check-upload.yaml new file mode 100644 index 000000000..1794cb096 --- /dev/null +++ b/examples/certificate-check-upload.yaml @@ -0,0 +1,53 @@ +# An example Job to run a certificate check of OpenShift's internal +# certificate status from within OpenShift. +# +# The generated reports are uploaded to a location in the master +# hosts, using the playbook 'easy-mode-upload.yaml'. +# +# This example uses the openshift/origin-ansible container image. +# (see README_CONTAINER_IMAGE.md in the top level dir for more details). +# +# The following objects are expected to be configured before the creation +# of this Job: +# - A ConfigMap named 'inventory' with a key named 'hosts' that +# contains the the Ansible inventory file +# - A Secret named 'sshkey' with a key named 'ssh-privatekey +# that contains the ssh key to connect to the hosts +# (see examples/README.md for more details) +--- +apiVersion: batch/v1 +kind: Job +metadata: + name: certificate-check +spec: + parallelism: 1 + completions: 1 + template: + metadata: + name: certificate-check + spec: + containers: + - name: openshift-ansible + image: openshift/origin-ansible + env: + - name: PLAYBOOK_FILE + value: playbooks/certificate_expiry/easy-mode-upload.yaml + - name: INVENTORY_FILE + value: /tmp/inventory/hosts # from configmap vol below + - name: ANSIBLE_PRIVATE_KEY_FILE # from secret vol below + value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey + - name: CERT_EXPIRY_WARN_DAYS + value: "45" # must be a string, don't forget the quotes + volumeMounts: + - name: sshkey + mountPath: /opt/app-root/src/.ssh/id_rsa + - name: inventory + mountPath: /tmp/inventory + volumes: + - name: sshkey + secret: + secretName: sshkey + - name: inventory + configMap: + name: inventory + restartPolicy: Never diff --git a/examples/certificate-check-volume.yaml b/examples/certificate-check-volume.yaml new file mode 100644 index 000000000..dd0a89c8e --- /dev/null +++ b/examples/certificate-check-volume.yaml @@ -0,0 +1,60 @@ +# An example Job to run a certificate check of OpenShift's internal +# certificate status from within OpenShift. +# +# The generated reports are stored in a Persistent Volume using +# the playbook 'html_and_json_timestamp.yaml'. +# +# This example uses the openshift/origin-ansible container image. +# (see README_CONTAINER_IMAGE.md in the top level dir for more details). +# +# The following objects are expected to be configured before the creation +# of this Job: +# - A ConfigMap named 'inventory' with a key named 'hosts' that +# contains the the Ansible inventory file +# - A Secret named 'sshkey' with a key named 'ssh-privatekey +# that contains the ssh key to connect to the hosts +# - A PersistentVolumeClaim named 'certcheck-reports' where the +# generated reports are going to be stored +# (see examples/README.md for more details) +--- +apiVersion: batch/v1 +kind: Job +metadata: + name: certificate-check +spec: + parallelism: 1 + completions: 1 + template: + metadata: + name: certificate-check + spec: + containers: + - name: openshift-ansible + image: openshift/origin-ansible + env: + - name: PLAYBOOK_FILE + value: playbooks/certificate_expiry/html_and_json_timestamp.yaml + - name: INVENTORY_FILE + value: /tmp/inventory/hosts # from configmap vol below + - name: ANSIBLE_PRIVATE_KEY_FILE # from secret vol below + value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey + - name: CERT_EXPIRY_WARN_DAYS + value: "45" # must be a string, don't forget the quotes + volumeMounts: + - name: sshkey + mountPath: /opt/app-root/src/.ssh/id_rsa + - name: inventory + mountPath: /tmp/inventory + - name: reports + mountPath: /var/lib/certcheck + volumes: + - name: sshkey + secret: + secretName: sshkey + - name: inventory + configMap: + name: inventory + - name: reports + persistentVolumeClaim: + claimName: certcheck-reports + restartPolicy: Never diff --git a/examples/scheduled-certcheck-upload.yaml b/examples/scheduled-certcheck-upload.yaml new file mode 100644 index 000000000..05890a357 --- /dev/null +++ b/examples/scheduled-certcheck-upload.yaml @@ -0,0 +1,53 @@ +# An example ScheduledJob to run a regular check of OpenShift's internal +# certificate status. +# +# Each job will upload new reports to a directory in the master hosts +# +# The Job specification is the same as 'certificate-check-upload.yaml' +# and the expected pre-configuration is equivalent. +# See that Job example and examples/README.md for more details. +# +# NOTE: ScheduledJob has been renamed to CronJob in upstream k8s recently. At +# some point (OpenShift 3.6+) this will have to be renamed to "kind: CronJob" +# and once the API stabilizes the apiVersion will have to be updated too. +--- +apiVersion: batch/v2alpha1 +kind: ScheduledJob +metadata: + name: certificate-check + labels: + app: certcheck +spec: + schedule: "0 0 1 * *" # every 1st day of the month at midnight + jobTemplate: + metadata: + labels: + app: certcheck + spec: + template: + spec: + containers: + - name: openshift-ansible + image: openshift/origin-ansible + env: + - name: PLAYBOOK_FILE + value: playbooks/certificate_expiry/easy-mode-upload.yaml + - name: INVENTORY_FILE + value: /tmp/inventory/hosts # from configmap vol below + - name: ANSIBLE_PRIVATE_KEY_FILE # from secret vol below + value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey + - name: CERT_EXPIRY_WARN_DAYS + value: "45" # must be a string, don't forget the quotes + volumeMounts: + - name: sshkey + mountPath: /opt/app-root/src/.ssh/id_rsa + - name: inventory + mountPath: /tmp/inventory + volumes: + - name: sshkey + secret: + secretName: sshkey + - name: inventory + configMap: + name: inventory + restartPolicy: Never diff --git a/examples/scheduled-certcheck-volume.yaml b/examples/scheduled-certcheck-volume.yaml new file mode 100644 index 000000000..2f26e8809 --- /dev/null +++ b/examples/scheduled-certcheck-volume.yaml @@ -0,0 +1,58 @@ +# An example ScheduledJob to run a regular check of OpenShift's internal +# certificate status. +# +# Each job will add a new pair of reports to the configured Persistent Volume +# +# The Job specification is the same as 'certificate-check-volume.yaml' +# and the expected pre-configuration is equivalent. +# See that Job example and examples/README.md for more details. +# +# NOTE: ScheduledJob has been renamed to CronJob in upstream k8s recently. At +# some point (OpenShift 3.6+) this will have to be renamed to "kind: CronJob" +# and once the API stabilizes the apiVersion will have to be updated too. +--- +apiVersion: batch/v2alpha1 +kind: ScheduledJob +metadata: + name: certificate-check + labels: + app: certcheck +spec: + schedule: "0 0 1 * *" # every 1st day of the month at midnight + jobTemplate: + metadata: + labels: + app: certcheck + spec: + template: + spec: + containers: + - name: openshift-ansible + image: openshift/origin-ansible + env: + - name: PLAYBOOK_FILE + value: playbooks/certificate_expiry/html_and_json_timestamp.yaml + - name: INVENTORY_FILE + value: /tmp/inventory/hosts # from configmap vol below + - name: ANSIBLE_PRIVATE_KEY_FILE # from secret vol below + value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey + - name: CERT_EXPIRY_WARN_DAYS + value: "45" # must be a string, don't forget the quotes + volumeMounts: + - name: sshkey + mountPath: /opt/app-root/src/.ssh/id_rsa + - name: inventory + mountPath: /tmp/inventory + - name: reports + mountPath: /var/lib/certcheck + volumes: + - name: sshkey + secret: + secretName: sshkey + - name: inventory + configMap: + name: inventory + - name: reports + persistentVolumeClaim: + claimName: certcheck-reports + restartPolicy: Never |