Working_with_bookbag.adoc

Table of Contents

• Working with Bookbag
  • What is "bookbag"
• Implementing and Using Bookbag in your Configs and Catalog Items
  • Configuring bookbag to run with an OpenShift (OCP) CI
  • Configuring bookbag to run on a traditional infrastructure CI

Working with Bookbag

This document gives an overview of working with the bookbag workshop console.

What is "bookbag"

Bookbag is the name given to web-based UI that allows users to interact with demos, workshops, and labs by their browser. In a typical, customizable, configuration, it provides a number of frames with content such as:

• HTML demos with navigation

• Terminal(s)

• Consoles

In the example below we see a pretty typical example of a Bookbag UI with the workshop on the left and 2 resizable Terminal sessions on the right.

General Bookbag Resources

• Template Repo

  • (Bookbag is implemented via a Container Image typically running on OpenShift, K8S, or a Container Engine)

• Agnosticd’s primary bookbag role

Warning

There are other "bookbag" roles within AgnosticD, do not use unless you fully understand your use case.

Warning

We’ve found that bookbag might need to be run BEFORE Let’s Encrypt

Implementing and Using Bookbag in your Configs and Catalog Items

This section will assume some familiarity with setting up catalog items via Agnostic V. However, much of this is equally pertinent to running book bag locally from your laptop via a var file.

Configuring bookbag to run with an OpenShift (OCP) CI

These configuration guidelines below apply equally to a standalone or dedicated OpenShift catalog item or a shared item. There is no configuration difference between these two different scenarios. This section also assumes some familiarity with the OpenShift workload pattern and AgnosticV.

Note	Non AgnosticV users can just add these to their var file and pass via -e @my_vars.yaml

A typical AgnosticV common.yaml with Bookbag configured

infra_workloads:
  - ocp4_workload_le_certificates
  - ocp4_workload_lpe_automation_controller
  - bookbag (1)

bookbag_git_repo: https://github.com/tonykay/wasm-oci-workshop.git (2)
bookbag_git_version: development # commit | tag | branch (3)

1. Bookbag is the final role, or workload, listed in our infra_workloads list

   Important

   bookbag consumes user_data so it must be called after all other workloads have run, to have visibility of that data.

2. Mandatory, set the bookbag_git_repo var to point at your bookbag repo

3. Optional, the bookbag_git_version repo allows users to specify a branch, tag, or commit

Note	The bookbag_git_version variable allows developers to both make changes and guarantee stability. For example, if using a typical AgnosticV entry a developer could take this approach:

dev.yaml

infra_workloads:
  - ocp4_workload_le_certificates
  - ocp4_workload_lpe_automation_controller
  - bookbag

bookbag_git_repo: https://github.com/tonykay/wasm-oci-workshop.git
bookbag_git_version: development  # head of development branch

event.yaml

infra_workloads:
  - ocp4_workload_le_certificates
  - ocp4_workload_lpe_automation_controller
  - bookbag

bookbag_git_repo: https://github.com/tonykay/wasm-oci-workshop.git
bookbag_git_version: workshop-wasm-0.3.0 # Stable git tag

Note	The above examples have some, unnecessary redundancy as typically both the role bookbag and the var bookbag_git_repo would live in common.yaml

Configuring bookbag to run on a traditional infrastructure CI

In this section, we’re going to look at how we would use bookbag when deploying a traditional infrastructure based config via a Catalog Item (CI). By traditional infrastructure, we mean an item that does not use OpenShift but deploys to VMs or instances.

Bookbag, itself still runs on a, shared, OpenShift cluster. So the implication here is that your CI should have the ability to authenticate and deploy to the cluster, in addition to whatever cloud provider it needs. Fortunately, as we will see, this is very straightforward in AgnosticV.

The final consideration is your AgnosticD config must call the bookbag role. Again this is very straightforward.

Setting up your config to deploy, and destroy, bookbag

A good example of a config that correctly deploys and destroys bookbag is base-aap2-infra

1. Calling the bookbag role.

   As with an OCP-based config, bookbag needs to be called as late as possible as it relies on user_info. Therefore it should be the last role called, except for any final verification logic, in post_software.yml. See this example

   - name: Deploy Bookbag
     when: bookbag_git_repo is defined
     ansible.builtin.include_role:
       name: bookbag
     vars:
       ACTION: create

2. Destroying bookbag and cleanup

   As bookbag is deployed to a resource external to your CI, ie an external OpenShift Cluster, you are responsible for the cleanup when your deployment is destroyed or torn down. To do this your config needs to have a destroy_env.yml containing the following.

    - name: Include role to destroy Bookbag
      when: bookbag_git_repo is defined
      ansible.builtin.include_role:
        name: bookbag
      vars:
        ACTION: destroy

   See this example for reference

Now your config is set up to deploy and destroy bookbag you need to configure your CI in AgnosticV or in an external var file.

Setting up your config to deploy, and destroy, bookbag

AgnosticV configuration again is very similar to that of OCP-based CIs, with the simple addition of the necessary secret to authenticate to an existing, shared, OCP cluster. Fortunately, you should not have to define this secret yourself but include it.

1. Typical common.yaml variables for bookbag

   #include /includes/secrets/bookbag-shared-410.yaml
   
   bookbag_git_repo: https://github.com/tonykay/wasm-oci-workshop.git
   bookbag_git_version: workshop-wasm-0.3.0 # Optional commit | tag | branch

   Confer with your Cluster Admin if you are unsure about which secret to #include