Doc updates

[PhillypHenning]

[PhillypHenning]

Local development page 🧵

[PhillypHenning]

We assume that at this point you've at the very least cloned the repo locally and have it open in your favorite editor. If you haven't made it there, please take a moment to get yourself set up and comfortable.

Build BitOps-base

docker build -t bitops-base:latest .

The initial build of BitOps runs through the commands to setup the bitops container environment. At this point it has not installed any plugins, only a short list of utilities and tools that BitOps will directly use. Things such as python3, jq, etc

Create a plugins.dockerfile

Create a file in the root level of bitops named Dockerfile.plugins with the content;

FROM bitops-base:latest

Build BitOps (with plugins)

docker build -t bitops:latest . -f Dockerfile.plugins

Run BitOps

docker run \
  -e BITOPS_ENVIRONMENT=/path/to/environment  \
  -e AWS_DEFAULT_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=your-aws-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key \
  -v /path/to/operations_repo:/opt/bitops_deployment \
  bitops:latest

Benefits to local testing

• configuration validation
• rapid testing of new features
• get your hands dirty!

[PhillypHenning]

MKDocs 🧵

[PhillypHenning]

@mickmcgrath13 / @ConnorGraham
What are your thoughts on hosting cloud-configuration and tool-configuration in our docs with plugins?

How do we keep parity between what's documented by bitops and what is contained in the plugins?

[mickmcgrath13]

eventually, I think we should have a build process at the bitops docs level that pulls in docs for each plugin, too.

for now, I'd say we have the raw docs as follows:

• ops repo, core stuff - bitops repo
• plugin specifics - each plugin repo
• guides for specific plugins and how they interact together - bitops repo (note the plugin version)

I think we could have some references to plugins in the bitops repo (i.e. high level details and a link to the plugin docs/readme)

thoughts?

cc @armab

[mickmcgrath13]

relevant slack thread: https://bitovi-community.slack.com/archives/C01SX5L134G/p1658413076579069

[PhillypHenning]

Sounds good.

So the plan is;
Today

• Get the docs written and we can host them in BitOps source

Action items

• Move plugin relevant doc into the plugin and create CI pipeline that pulls the doc

[ccapell]

IMO

• Plugins should store their own documentation
• BitOps Core should store its own documentation
• And a new repo called plugin-framework or something.
  • Has the plugin structure, and required files, even if the files don't contain much
  • Documentation in this repo is how to build a custom plugin
    • How to submit to Bitovi for inclusion in the plugins project?

[PhillypHenning]

👍 The first two points are noted

I've created two plugin examples for people;

• https://github.com/bitops-plugins/example-plugin
• https://github.com/bitops-plugins/template

[PhillypHenning]

Custom image creation 🧵

[PhillypHenning]

In this section we will learn how we can create a custom BitOps image with plugins and additional utilities.

Clone Bitops source

First thing is first, if you haven't already clone the github bitops repo locally
git clone https://github.com/bitovi/bitops.git

---

Modify the bitops.config.yaml

Using your preferred editor, open the root level bitops.config.yaml

This file is used to configure the BitOps image.

Example bitops.config.yaml

---

bitops.config.yaml

BitOps "official" image

Below is an example of how the "official" image of bitops is configured.

As you can see there are two sections we need to be aware of; Plugins and Deployments.

plugins

Defines a plugin and the source for that plugin.

Deployment

Defines alias', the sequence of executions for those alias' and the alias' related plugin.

official image

  plugins:    
    aws:
      source: https://github.com/bitops-plugins/aws
    terraform:
      source: https://github.com/bitops-plugins/terraform
    cloudformation:
      source: https://github.com/bitops-plugins/cloudformation
    helm:
      source: https://github.com/bitops-plugins/helm
    kubectl:
      source: https://github.com/bitops-plugins/kubectl
    ansible:
      source: https://github.com/bitops-plugins/ansible
  deployments:
    cloudformation:
      plugin: cloudformation
    terraform:
      plugin: terraform
    helm:
      plugin: helm
    ansible:
      plugin: ansible

---

Custom image example

plugins:
    plugin-name-1:
        source: url-to-plugin-1
    plugin-name-2:
        source: url-to-plugin-2
deployments:
    alias-name-1:
        plugin: plugin-name-1
    alias-name-2:
        plugin: plugin-name-2
    alias-name-3:
        plugin: plugin-name-1

In the above example we define 2 plugins that BitOps will install, plugin-name-1 and plugin-name-2.

In the deployment section we specify 3 alias' that we will act on in our ops_repo. We also specify which plugin we'd like to make that action.

So continuing with our example above, the ops_repo would look like;

OPS_REPO/
    ENV/
        alias-name-1/
            ... 
        alias-name-2/
            ...
        alias-name-3/
            ...

OPS_REPO/
    ENV/
        alias-name-1/ # <-- plugin-name-1 would be actioned on this folder
            ... 
        alias-name-2/ # <-- plugin-name-2 would be actioned on this folder
            ...
        alias-name-3/ # <-- plugin-name-1 would be actioned on this folder
            ...

Build and run the image

The final steps are to build and run the image. You can find example commands to accomplish this in

[PhillypHenning]

Docs have been created capturing this