Merge pull request #127 from f5devcentral/develop

Pull from Devel to Master

README.md

@@ -20,7 +20,7 @@ Class 8- Containers - Kubernetes & OpenShift Integration with BIG-IP
 
 Class 9- Basic BIG-IP Configuration Management with Ansible
 
-Class 10- Advanced BIG-IP Configuration Management with Ansible
+Class 10- Mastering Imperative and Declarative Automation with F5 BIG-IP
 
 Class 11- 101 of Terraform BIG-IP Provider
 

docs/class10/AS3/00-Backup-Restore-Role_as3.rst

@@ -0,0 +1,92 @@
+Use-Case 00: Backup And Restore Role
+====================================
+
+OVERVIEW
+--------
+
+This is a great example of best practices when doing major configurations with a BIG-IP. Having a backup of your previous configuration ensures that you can return to a point in time that was a known working configuration if something were to break.
+
+Backup-Role.yaml is a templated Ansible play that utilizes an underlying Role that demonstrates the ability to backup a BIG-IP Configuration to a UCS File then download that UCS file to /tmp/Use-Case-00-backup.ucs on the local ansible box. This is to ensure a backup within the BIG-IP and a backup local to your machine.
+
+Restore-Role.yaml is a templated Ansible play that utilizes an underlying Role that demonstrates the ability to restore a BIG-IP Configuration with the locally stored UCS File in "/tmp/Use-Case-00-backup.ucs". This play has a check to ensure that the UCS file exists before it can run a restore. 
+
+.. attention::
+
+   The restore command will produce an error in some builds of Ansible even though the restoration does complete. It is a known issue due to the reset of the RestAPI services.
+
+RUN THE TEMPLATE
+----------------
+
+Running this template assumes that a F5 BIG-IP instance, necessary webservers and Ansible node are available.
+
+   1. Ensure you are using a terminal from VSCode (UDF --> Ansible-Node --> Access --> Code-Server --> Password: Ansible123! --> Trust --> Terminal --> New Terminal)
+
+   2. Change Directory in the Ansible Host to the use-cases repo previously downloaded
+
+      .. code:: bash
+      
+         cd ~/f5-bd-ansible-labs/401-F5-AppWorld-Lab/AS3/00-Backup-Restore-Role/
+
+   3. **(Optional)** View 'vars/f5_vars.yml' file in the vars folder to see information about the deployment (i.e. local_folder_location)
+
+   4. Run the Ansible Playbook ‘Backup-Role.yaml’:
+
+      .. note:: 
+
+         If you have run the modules section of this lab and already executed a backup then this run is necessary.
+
+      .. code:: bash
+      
+         ansible-navigator run Backup-Role.yaml --mode stdout
+
+      In this example, the playbook looks for the Folder-Location and File-Name variables as specified in the vars/f5_vars.yaml file and uses that information to tell the BIG-IP to run a backup and then export that file to where the Folder-Location and File-Name variables points to.
+
+   5. **(Optional)** Run the Ansible Playbook ‘Restore-Role.yaml’:
+      If you have run the Modules section of this lab and already executed a backup and want to test the AS3 section then it is **(Recommended)** to run a restore
+
+      .. code:: bash
+      
+         ansible-navigator run Restore-Role.yaml --mode stdout
+
+      .. note::
+
+         you might see an error that looks like `fatal: [f5 -> localhost]: FAILED! => {"changed": false, "msg": "Expecting value: line 1 column 1 (char 0)"}`  this can occurs due to restarting of services and shouldn't impact the effect of the restore.  
+
+         after the command is run wait up to 5 minutes for the restore to complete.
+
+      .. note::
+
+         after the restoration of the backup you might see notifications that the F5 needs to be rebooted, this is something that can be ignored for this lab as it has to deal with the deprovisioning of modules, it doesnt impact the lab and future runs. 
+
+         after the command is run wait up to 5 minutes for the restore to complete.
+
+      In this example, the playbook looks for the Folder-Location and File-Name variables as specified in the vars/f5_vars.yaml file and uses that information to upload the configuration (if exists) to the BIG-IP to run a restore.
+
+TESTING AND VALIDATION
+-----------------------
+
+**BIG-IP CONFIGURATION VERIFICATION:**
+
+This section is optional and for testing and verification purposes only. It assumes knowledge of how to operate BIG-IP commands and networking.
+
+
+
+   **Ansible Host:**
+
+   - Within a terminal window run `ls /f5/code-output/` to verify the backup file exists
+   - This file will be named based on the inventory-hostname-Year-Month-Day-Hour-Minute-Second.ucs `e.g. f5-2024-12-13-03-27-51.ucs`.
+   - This method was used to ensure date/timestamps of backups on files and prevents overwriting of other backups. 
+
+
+   **F5 BIG-IP**
+
+   - BIG-IP - (In UDF --> Components --> BIG-IP --> Access --> TMUI)  - This will popup a webpage to access the F5 Login Page
+
+      - Login to the BIG-IP instance  
+      - Navigate to System --> Archives  
+      - There should be an archive file named similarly to `f5-2024-12-13-03-27-51.ucs` based on the date/timestamp
+
+   - Login information for the BIG-IP:
+
+      * username: admin 
+      * password: **found in the inventory hosts file**

docs/class10/AS3/01-Deploy-SSL-Enabled-App_Services_as3.rst

@@ -0,0 +1,74 @@
+Use-case 01: Deploy SSL enabled App-service with AS3
+====================================================
+
+OVERVIEW
+--------
+Deploy-SSL-Enabled-App_Services.yaml is a templated Ansible playbook that utilizes AS3 that demonstrates configuring SSL termination and SSL re-direct for your application on F5 BIG-IP. 
+
+Using this template, we will create an SSL enabled (on port 443) application service (Virtual IP or VIP) on F5 BIG-IP and also create the associative Port 80 SSL redirect for that Virtual IP. If there is an already existing application service (VIP) that was previously deployed without SSL (a very common scenario), this template will also enable SSL (open SSL port) on that Virtual IP address.
+
+The certificates used in this template for SSL termination are self-signed certs that are generated on the BIG-IP. Users will be able to swap out the self-signed certs very easily and we will demonstrate how in 'certificate-replacement' template that will follow.
+
+RUN THE TEMPLATE
+----------------
+Running this template assumes that a F5 BIG-IP instance, necessary webservers and Ansible node are available.  
+
+  1. Ensure you are using a terminal from VSCode (UDF --> Ansible-Node --> Access --> Code-Server --> Password: Ansible123! --> Trust --> Terminal --> New Terminal)
+
+  2. Change Directory in the Ansible Host to the use-cases repo previously downloaded
+
+    .. code::
+    
+        cd ~/f5-bd-ansible-labs/401-F5-AppWorld-Lab/AS3/01-Deploy-SSL-Enabled-App_Services-AS3/
+
+  3. Run the Ansible Playbook ‘Deploy-SSL-Enabled-App_Services.yaml’:
+
+    .. code::
+    
+        ansible-navigator run Deploy-SSL-Enabled-App_Services.yaml --mode stdout
+
+    .. note:: 
+
+        Any errors seen on the screen are expected behavior and can be ignored.
+
+TESTING AND VALIDATION
+-----------------------
+
+**VERIFYING RE-DIRECT SERVICE:**
+
+   **Access Using F5 UDF Console:**
+
+      Using the External Client (UDF --> Components --> External Client --> Access --> Firefox)
+
+      - In the Bookmarks bar you can select the ``Ansible Labs`` Folder and goto ``401 - Labs`` and Select ``Use Case 1 - HTTP or Use Case 1 - HTTPS`` 
+      - OR within the browser you can browse to https://10.1.20.30/
+      - You will need to bypass the certificate warning (within Firefox Warning --> Advanced --> Accept the Risk and Continue)
+
+      .. note::
+
+         Your browser is presented with a certificate (clientssl cert) that is built with the BIG-IP.
+
+         You will therefore see an `unsafe` message from your browser which is expected in this demo. Click proceed to website.
+
+      |
+
+**BIG-IP CONFIGURATION VERIFICATION:**
+
+This section is optional and for testing and verification purposes only. It assumes knowledge of how to operate BIG-IP commands and networking.
+
+   **Access Using F5 UDF Console:**
+
+   - BIG-IP - (In UDF --> Components --> BIG-IP --> Access --> TMUI)  - This will popup a webpage to access the F5 Login Page
+
+      * Login to the BIG-IP instance
+      * Navigate to Local Traffic --> Virtual Servers
+      * Change the Partition (Top Right Corner) to "WorkshopExample"
+      * Ensure there are 2 VIPs with same IP
+
+         + One listening on port 443
+         + One listening on port 80
+
+   - Login information for the BIG-IP:
+
+      * username: admin 
+      * password: **found in the inventory hosts file**

docs/class10/AS3/02-Replace-Application-Certificates_as3.rst

@@ -0,0 +1,176 @@
+Use Case 02: Replace Application Certificates with AS3
+======================================================
+
+OVERVIEW
+--------
+Replace-Application-Certificates.yaml is a templated Ansible playbook that is used to demonstrate automation for managing certificates and keys used by your application services with AS3.
+
+Being able to create and swap SSL Profiles on a BIG-IP to singular or multiple VIPs is extremely useful, especially in today’s world where SSL keys get leaked, systems and applications get hacked, certificates become stale or expire. This automated method allows a seamless process to create and change certificates based on need/demand.
+
+This use case template will create a new application service (VIP) on the F5 BIG-IP that will use a custom key and certificate to terminate client's SSL connection. 
+
+RUNNING THE TEMPLATE
+--------------------
+Running this template assumes that a F5 BIG-IP instance, necessary webservers and Ansible node are available.  
+
+  1. Ensure you are using a terminal from VSCode (UDF --> Ansible-Node --> Access --> Code-Server --> Password: Ansible123! --> Trust --> Terminal --> New Terminal)
+
+  2. Change Directory in the Ansible Host to the use-cases repo previously downloaded
+
+    .. code::
+    
+        cd ~/f5-bd-ansible-labs/401-F5-AppWorld-Lab/AS3/02-Replace-Application-Certificates-AS3/
+
+  3. Run the Ansible Playbook ‘Replace-Application-Certificates.yaml’:
+
+    .. code::
+
+        ansible-navigator run Replace-Application-Certificates.yaml --mode stdout
+
+
+AS3 Declarations
+----------------
+In this module we will discuss a little bit more about AS3 declarations and how they differ from calling modules.  in AS3 the json templates become the single source of truth for the tenant partition.
+When using Modules every action is done sequentially but also doesnt take away from the previous command, where as AS3 if a VIP is in the template it will be there, and if between runs the VIP is not there it is removed.
+
+In this code we have our base template (tennant_base.j2) this code sets up our tenant and fills it in with the variable as3_app_body which is a rendering of as3_template.j2 file with ansible filling in variable areas.
+
+  .. code::  yaml
+
+      {
+         {
+         "class": "AS3",
+         "action": "deploy",
+         "persist": true,
+         "declaration": {
+            "class": "ADC",
+            "schemaVersion": "3.2.0",
+            "id": "ansibleusecases",
+            "label": "Ansible Workshops",
+            "remark": "Tenant-multi-app",
+            "{{ as3_tenant_name }}":{
+                  "class": "Tenant",
+                  {{ as3_app_body }}
+            }
+         }
+      }
+
+
+In this code we have the two usecases (Use Case 1's code and Use Case 2's code), if use Case 1's code would not have been in this template then it would only deploy use case 2's virtual server.  This is an example of how a AS3 template with multiple applications are built.
+
+  .. code::  yaml
+
+         "AS3-UseCase-1": {
+         "class": "Application",
+         "{{F5_VIP_Name_UC1}}": {
+            "class": "Service_HTTPS",
+            "virtualAddresses": [
+               "{{ private_ip }}"
+            ],
+            "profileMultiplex": {
+               "bigip": "/Common/oneconnect"
+            },
+            "pool": "{{ F5_VIP_Name_UC1 }}_pool",
+            "serverTLS": {
+               "bigip": "/Common/clientssl"
+            },
+            "persistenceMethods": []
+         },
+         "{{ F5_VIP_Name_UC1 }}_pool": {
+            "class": "Pool",
+            "minimumMembersActive": 0,
+            "minimumMonitors": "all",
+            "monitors": [
+               "http"
+            ],
+            "members": [{
+               "servicePort": 80,
+               "serverAddresses": [
+                     {% set comma = joiner(",") %}
+                     {% for mem in pool_members %}
+                           {{comma()}} "{{  hostvars[mem]['private_ip']  }}"
+                     {% endfor %}
+               ]
+            }]
+         }
+         },
+         "AS3-UseCase-2": {
+            "class": "Application",
+            "{{F5_VIP_Name}}": {
+               "class": "Service_HTTPS",
+               "virtualPort": 8082,
+               "virtualAddresses": [
+                  "{{ private_ip }}"
+               ],
+               "pool": "{{ F5_VIP_Name }}_pool",
+               "redirect80": false,
+               "profileMultiplex": {
+                  "bigip": "/Common/oneconnect"
+               },
+               "serverTLS": "{{ F5_VIP_Name }}_cert",
+               "persistenceMethods": []
+            },
+            "{{ F5_VIP_Name }}_pool": {
+               "class": "Pool",
+               "minimumMembersActive": 0,
+               "minimumMonitors": "all",
+               "monitors": [
+                  "http"
+               ],
+               "members": [{
+                  "servicePort": 80,
+                  "serverAddresses": [
+               {% set comma = joiner(",") %}
+               {% for mem in pool_members %}
+                  {{comma()}} "{{  hostvars[mem]['private_ip']  }}"
+               {% endfor %}
+         ]
+               }]
+            },
+            "{{ F5_VIP_Name }}_cert": {
+               "class": "TLS_Server",
+               "certificates": [{
+                  "certificate": "{{ F5_VIP_Name }}_crt"
+               }]
+            },
+            "{{ F5_VIP_Name }}_crt": {
+               "class": "Certificate",
+               "remark": "in practice we recommend using a passphrase",
+               "certificate": "{{ lookup('file', '{{playbook_dir}}/app-demo.crt') | replace('\n', '\\n') }}",
+               "privateKey": "{{ lookup('file', '{{playbook_dir}}/app-demo.key') | replace('\n', '\\n') }}"
+            }
+         }
+
+In this section we focus on Use Case 2 but we wanted to provide an example of how AS3 stacks applications within a single template.
+
+TESTING AND VALIDATION
+----------------------
+
+**CERTIFICATE VERIFICATION**
+
+   **Access Using F5 UDF Console:**
+
+   Using the External Client (UDF --> Components --> External Client --> Access --> Firefox)
+
+      - In the Bookmarks bar you can select the ``Ansible Labs`` Folder and goto ``401 - Labs`` and Select ``Use Case 2`` 
+      - OR within the browser you can browse to https://10.1.20.30:8082/
+      - From a client browser, access the VIP on port 8081 to view the new self-signed certificate (https://10.1.20.30:8082)
+
+
+**BIG-IP CONFIGURATION VERIFICATION**
+
+This section is optional and for testing and verification purposes only. It assumes knowledge of how to operate BIG-IP commands and networking.
+
+   **Access Using F5 UDF Console:**
+
+   - BIG-IP - (In UDF --> Components --> BIG-IP --> Access --> TMUI)  - This will popup a webpage to access the F5 Login Page
+
+      * Login to the BIG-IP instance
+      * Navigate to Local Traffic --> Virtual Servers
+      * Change the Partition (Top Right Corner) to "WorkshopExample"
+      * View the deployed use case access VIP:port (8082)
+
+   - Login information for the BIG-IP:
+
+      * username: admin 
+      * password: **found in the inventory hosts file**