view | history | commit | commitdiff
Wolfgang Kulhanek
2020-03-16 96f73bbfe948e2a2789c7f609bfac6308926eaa3
commit | author | age
c8774c 1 = ocp-workload-example - Example Workload Role
WK 2
3 == Role overview
4
5 * This is a working no-op role that can be used to develop new ocp-workload roles. It consists of the following playbooks:
6 ** Playbook: link:./tasks/pre_workload.yml[pre_workload.yml] - Sets up an
7  environment for the workload deployment
8 *** Debug task will print out: `pre_workload Tasks completed successfully.`
9
10 ** Playbook: link:./tasks/workload.yml[workload.yml] - Used to deploy the actual
96f73b 11  workload, i.e, 3scale, Mobile, some Demo or OpenShift customization
c8774c 12 *** This role only prints the current username for which this role is provisioning.
WK 13 *** Debug task will print out: `workload Tasks completed successfully.`
14
15 ** Playbook: link:./tasks/post_workload.yml[post_workload.yml] - Used to
16  configure the workload after deployment
17 *** This role doesn't do anything here
18 *** Debug task will print out: `post_workload Tasks completed successfully.`
19
20 ** Playbook: link:./tasks/remove_workload.yml[remove_workload.yml] - Used to
21  delete the workload
22 *** This role doesn't do anything here
23 *** Debug task will print out: `remove_workload Tasks completed successfully.`
24
25 == Review the defaults variable file
26
27 * This file link:./defaults/main.yml[./defaults/main.yml] contains all the variables you need to define to control the deployment of your workload.
28 * The variable *ocp_username* is mandatory to assign the workload to the correct OpenShift user.
29 * A variable *silent=True* can be passed to suppress debug messages.
30 * You can modify any of these default values by adding `-e "variable_name=variable_value"` to the command line
96f73b 31 * Add a dictionary for workload parameters.
WK 32
33 == Understand how paremeters to your workload should be specified
34
35 === Overview
36
37 A `dictionary` approach should be used in order to neatly encapsulate parameters to roles.
38
39 The role itself defines a dictionary `<role name>_defaults` in the file link:./defaults/main.yml[./defaults/main.yml]. Because this example role is `ocp-workload-example` the dictionary is called `ocp_workload_example_defaults`. Note that `_` is used instead of `-` in the dictionary name to create a valid Ansible dictionary name.
40
41 When deploying a workload you can specify another dictionary with the specific parameters for this deployment. This dictionary should be called `<role name>_vars`. In our example this dictionary would be called `ocp_workload_example_vars`.
42
43 === Handling secret parameters
44
45 In case you need to pass a secret parameter (e.g. the Bind Password for an LDAP server) you may define another dictionary, `<role name>_secrets`, and pass that as well.
46
47 [TIP]
48 When setting default values for secrets in the *defaults* dictionary be careful what you set. `""` is probably a good choice. Some workloads (ocp4-workload-authentication for example) generate passwords if a password is not being specified. If you set a default password in the defaults dictionary this logic will never be executed.
49
50 For deployment via AgnosticD/AgnosticV the contents of this secrets dictionary need to be placed on the provisioning host and referenced in the AgnosticV configuration.
51
52 === Combined dictionary
53
54 When running your workload the first task in link:./tasks/workload.yml[./tasks/workload.yml] sets up the combined dictionary with name `<role name>`. The defaults are combined with vars and secrets. In that order. This means that values in *defaults* can be overridden with values in *vars* and *secrets*.
55
56 When adapting this example role for your particular workload make sure to update the dictionary names in both link:./tasks/workload.yml[./tasks/workload.yml] and link:./tasks/remove_workload.yml[./tasks/remove_workload.yml] files.
57
c8774c 58
WK 59 === Deploy a Workload with the `ocp-workload` playbook [Mostly for testing]
60
96f73b 61 . If your workload uses parameters create a `<role name>_vars.yaml` input file.
WK 62 +
63 .ocp_workload_example_vars.yaml
64 [source,yaml]
c8774c 65 ----
96f73b 66 # You can set any variable, not just the dictionary
WK 67 silent: true
68
69 # Set up the `vars` dictionary
70 ocp_workload_example_vars:
71   variable_2: "My variable 2"
72 ----
73
74 . If your workload uses secrets create a `<role name>_secrets.yaml` input file.
75 +
76 .ocp_workload_example_secrets.yaml
77 [source,yaml]
78 ----
79 # Set up the `secrets` dictionary
80 ocp_workload_example_secrets:
81   variable_secret: "top secret data"
82 ----
83
84 . Set up Environment Variables for the bastion you want to run this role on.
85 +
86 [source,yaml]
87 ----
88 TARGET_HOST="bastion.dev.openshift.opentlc.com"
89 OCP_USERNAME="wkulhane-redhat.com"
90 ANSIBLE_USER="ec2-user"
889a28 91 WORKLOAD="ocp-workload-example"
c8774c 92 GUID=1001
96f73b 93 ----
c8774c 94
96f73b 95 . Finally run the workload passing the input files as parameters:
WK 96 +
97 [source,sh]
98 ----
c8774c 99 # a TARGET_HOST is specified in the command line, without using an inventory file
WK 100 ansible-playbook -i ${TARGET_HOST}, ./configs/ocp-workloads/ocp-workload.yml \
889a28 101     -e"ansible_ssh_private_key_file=~/.ssh/keytoyourhost.pem" \
96f73b 102     -e"ansible_user=${ANSIBLE_USER}" \
889a28 103     -e"ocp_username=${OCP_USERNAME}" \
WK 104     -e"ocp_workload=${WORKLOAD}" \
105     -e"guid=${GUID}" \
96f73b 106     -e"ACTION=create" \
WK 107     -e @./ocp_workload_example_vars.yaml \
108     -e @./ocp_workload_example_secrets.yaml
109 ----
110 +
111 Note how the dictionary got set up:
112
113 * *Variable 1: value 1* This value comes from the *defaults* dictionary. It did not get overwritten anywhere
114 * *Variable 2: My variable 2* This value comes from the *vars* dictionary that was passed as a parameter
115 * *Variable Secret: top secret data* This value comes from the *secrets* dictionary that was passed as a parameter
116 +
117 .Example output when using the examples above:
118 [source,text,options="nowrap"]
119 ----
120 [...]
121
122 TASK [ocp-workload-example : Running Pre Workload Tasks] *****************************************************************************************************************************************************************
123 Monday 16 March 2020  15:27:10 -0400 (0:00:00.070)       0:00:05.383 **********
124 included: /Users/wkulhane/Development/agnosticd/ansible/roles/ocp-workload-example/tasks/./pre_workload.yml for bastion.dev4.openshift.opentlc.com
125
126 TASK [ocp-workload-example : Set up ocp4_workload_example combined dictionary] *******************************************************************************************************************************************
127 Monday 16 March 2020  15:27:10 -0400 (0:00:00.051)       0:00:05.434 **********
128 ok: [bastion.dev4.openshift.opentlc.com]
129
130 [...]
131
132 TASK [ocp-workload-example : Setting up workload for user] ***************************************************************************************************************************************************************
133 Monday 16 March 2020  15:27:10 -0400 (0:00:00.047)       0:00:05.625 **********
134 ok: [bastion.dev4.openshift.opentlc.com] => {
135     "msg": "Setting up workload for user ocp_username = wkulhane-redhat.com"
136 }
137
138 TASK [ocp-workload-example : Print Example Variables] ********************************************************************************************************************************************************************
139 Monday 16 March 2020  15:27:10 -0400 (0:00:00.032)       0:00:05.658 **********
140 ok: [bastion.dev4.openshift.opentlc.com] => (item=Variable 1: value 1.) => {
141     "msg": "Variable 1: value 1."
142 }
143 ok: [bastion.dev4.openshift.opentlc.com] => (item=Variable 2: My variable 2.) => {
144     "msg": "Variable 2: My variable 2."
145 }
146 ok: [bastion.dev4.openshift.opentlc.com] => (item=Variable Secret: top secret data) => {
147     "msg": "Variable Secret: top secret data"
148 }
149
150 [...]
c8774c 151 ----
WK 152
153 === To Delete an environment
889a28 154
c8774c 155 ----
96f73b 156 TARGET_HOST="bastion.dev.openshift.opentlc.com"
WK 157 OCP_USERNAME="wkulhane-redhat.com"
158 ANSIBLE_USER="ec2-user"
889a28 159 WORKLOAD="ocp-workload-example"
c8774c 160 GUID=1002
WK 161
162 # a TARGET_HOST is specified in the command line, without using an inventory file
163 ansible-playbook -i ${TARGET_HOST}, ./configs/ocp-workloads/ocp-workload.yml \
889a28 164     -e"ansible_ssh_private_key_file=~/.ssh/keytoyourhost.pem" \
8fa982 165     -e"ansible_user=ec2-user" \
889a28 166     -e"ocp_username=${OCP_USERNAME}" \
WK 167     -e"ocp_workload=${WORKLOAD}" \
168     -e"guid=${GUID}" \
96f73b 169     -e"ACTION=remove" \
WK 170     -e @./ocp_workload_example_vars.yaml \
171     -e @./ocp_workload_example_secrets.yaml
c8774c 172 ----
WK 173
96f73b 174 == Deploying a Workload with AgnosticV
c8774c 175
96f73b 176 When creating a configuration in AgnosticV that includes the deployment of the workload you can specify the dictionary straight in the AgnosticV config. Because AgnosticV configs are usually created by combining a `common.yaml` file with either `dev.yaml`, `test.yaml` or `prod.yaml` you can specify parts of the dictionary in each of these files. For example you could have common values defined in the `common.yaml` file and then specific values for development or production environments in `dev.yaml` or `prod.yaml`.
889a28 177
96f73b 178 AgnosticV merges the definition files starting with `common.yaml` and then adding/overwriting what comes from either `dev.yaml` or `prod.yaml`.
c8774c 179
96f73b 180 Example of a simple AgnosticV config:
WK 181
182 .common.yaml
c8774c 183 [source,yaml]
WK 184 ----
96f73b 185 # --- Quay Shared Workload Deployment for RPDS
WK 186 # --- System: RHPDS
187 # --- Catalog: OpenShift Demos
188 # --- Catalog Item: Quay 3 on OpenShift 4
189
190 # --- Platform
191 platform: rhpds
192
193 # --- Cloud Provider
194 cloud_provider: none
195
196 # --- Config
197 env_type: ocp-workloads
198 ocp_workload: ocp4-workload-quay-operator
199 # This workload must be run as ec2-user (or cloud-user on OpenStack)
200 # because it has tasks requiring sudo.
201 ansible_user: ec2-user
202 ansible_ssh_private_key_file: /home/opentlc-mgr/.ssh/opentlc_admin_backdoor.pem
203
204 # --- Ensure the workload prints the correct statements for CloudForms to realize it finished
205 workload_shared_deployment: true
206
207 # --- Workload Configuration
208 ocp4_workload_quay_operator_vars:
209   project: "quay-{{ guid }}"
210
211 # --- AgnosticV Meta variables
212 agnosticv_meta:
213   params_to_variables:
214     user: ocp_username
215   secrets:
216   # This secret file holds the token to pull the Quay image
217   - ocp4_workload_quay_secrets
c8774c 218 ----
WK 219
96f73b 220 .dev.yaml
WK 221 [source,yaml]
c8774c 222 ----
96f73b 223 purpose: development
c8774c 224
96f73b 225 # --- Use specific variable values for Development
WK 226 target_host: bastion.dev4.openshift.opentlc.com
c8774c 227
96f73b 228 # --- Workload Configuration Overrides
WK 229 # Deploy Quay v3.2.0
230 ocp4_workload_quay_operator_vars:
231   quay_image_tag: "v3.2.0"
232   clair_image_tag: "v3.2.0"
c8774c 233 ----
96f73b 234
WK 235 .prod.yaml
236 [source,yaml]
237 ----
238 ---
239 purpose: production
240
241 # --- Use specific variable values for Production
242 target_host: bastion.rhpds.openshift.opentlc.com
243
244 # --- Workload Configuration Overrides
245 ocp4_workload_quay_operator_vars:
246   quay_image_tag: "v3.1.3"
247   clair_image_tag: "v3.1.3"
248
249 # --- AgnosticV Meta variables
250 agnosticv_meta:
251   agnosticd_git_tag_prefix: ocp4-workload-quay-rhpds-prod
252 ----
253
254
255 == Complex Examples
256
257 If you want to see more examples of how this works in a real world workload the following workloads already use this approach:
258
259 * ocp4-workload-authentication
260 * ocp4-workload-machinesets
261 * ocp4-workload-logging
262 * ocp4-workload-quay-operator