Merge pull request #525 from puppetlabs/CAT-1333-use_more_relevant_ex…

…amples

(CAT-1333) - Use more relevant examples in docs

docs/md/content/litmus-concepts.md

@@ -81,7 +81,7 @@ There is currently no reason to consider alternatives to Bolt.
 
 Configuration for Litmus currently is spread over several files.
 The `provision.yaml` contains various lists of platforms to target for tests.
-The CI job setup (usually in `.travis.yml`, `appveyor.yml` or similar) contains the overall sequencing of steps for testing.
+The CI job setup (usually in `.travis.yml`, `appveyor.yml`, `Github Actions` or similiar) contains the overall sequencing of steps for testing.
 This setup is usually the same everywhere and is encoded in pdk-templates.
 There are slight variations to choose the puppet version and platform combinations from `provision.yaml`.
 

docs/md/content/usage/commands/command-reference.md

@@ -8,46 +8,47 @@ description: List of useful Litmus commands.
 
 Litmus has the ability to display more information when it is running, this can help you diagnose some issues. 
 
-```
+```bash
 export DEBUG=true
 ```
 
 ### Useful Docker commands
 
 To list all docker images, including stopped ones, run:
-```
+
+```bash
 docker ps -a
 ```
 
 You will get output similar to:
 
-```
+```bash
 docker container ls -a
 CONTAINER ID        IMAGE                      COMMAND                  CREATED              STATUS                     PORTS                  NAMES
-e7bc7e5b3d9b        litmusimage/oraclelinux7   "/bin/sh -c /usr/sbi…"   About a minute ago   Up About a minute          0.0.0.0:2225->22/tcp   litmusimage_oraclelinux7_-2225
-ae94def06077        litmusimage/oraclelinux6   "/bin/sh -c /sbin/in…"   3 minutes ago        Up 3 minutes               0.0.0.0:2224->22/tcp   litmusimage_oraclelinux6_-2224
-80b22735494e        litmusimage/centos6        "/bin/sh -c /sbin/in…"   5 minutes ago        Up 5 minutes               0.0.0.0:2223->22/tcp   litmusimage_centos6_-2223
-b7923a25f95b        ubuntu:14.04               "/bin/bash"              6 weeks ago          Exited (255) 4 weeks ago   0.0.0.0:2222->22/tcp   ubuntu_14.04-2222
+e7bc7e5b3d9b        litmusimage/oraclelinux9   "/bin/sh -c /usr/sbi…"   About a minute ago   Up About a minute          0.0.0.0:2225->22/tcp   litmusimage_oraclelinux9_-2225
+ae94def06077        litmusimage/oraclelinux8   "/bin/sh -c /sbin/in…"   3 minutes ago        Up 3 minutes               0.0.0.0:2224->22/tcp   litmusimage_oraclelinux8_-2224
+80b22735494e        litmusimage/stream9        "/bin/sh -c /sbin/in…"   5 minutes ago        Up 5 minutes               0.0.0.0:2223->22/tcp   litmusimage_centosstream9_-2223
+b7923a25f95b        ubuntu:22.04               "/bin/bash"              6 weeks ago          Exited (255) 4 weeks ago   0.0.0.0:2222->22/tcp   ubuntu_22.04-2222
 ```
 
 To stop and remove an image, run:
 
-```
-docker rm -f ubuntu_14.04-2222
+```bash
+docker rm -f ubuntu_22.04-2222
 ```
 
 To connect via ssh to the Docker image, run:
 
-```
+```bash
 ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@localhost -p 2222
 ```
 
 Note that you don't need to add to the known hosts file or check keys.
 
 To attach to the docker image and detach, run:
 
-```
-docker attach centos6
+```bash
+docker attach litmusimage_centosstream9_-2223
  to deattach <ctrl + p> then <ctrl + q>
 ```
 

docs/md/content/usage/commands/litmus-core-commands.md

@@ -17,6 +17,7 @@ Litmus has five commands:
 These commands allow you to create a test environment and run tests against your systems. Note that not all of these steps are needed for every deployment.
 
 Three common test setups are:
+
   * Run against localhost
   * Run against an existing machine that has Puppet installed
   * Provision a fresh system and install Puppet
@@ -37,9 +38,9 @@ Using the Litmus [provision](https://github.com/puppetlabs/provision) command, y
 
 For example:
 
-```
-pdk bundle exec rake 'litmus:provision[vmpooler, redhat-6-x86_64]'
-pdk bundle exec rake 'litmus:provision[docker, litmusimage/ubuntu:18.04]'
+```bash
+pdk bundle exec rake 'litmus:provision[vmpooler, redhat-9-x86_64]'
+pdk bundle exec rake 'litmus:provision[docker, litmusimage/ubuntu:22.04]'
 pdk bundle exec rake 'litmus:provision[vagrant, gusztavvargadr/windows-server]'
 ```
 
@@ -67,8 +68,8 @@ groups:
         host-key-check: false
     facts:
       provisioner: docker
-      container_name: centos_7-2222
-      platform: centos:7
+      container_name: centos_stream9-2222
+      platform: centos:stream9
 - name: winrm_nodes
   targets: []
 ```
@@ -79,7 +80,7 @@ Note that you can test some modules against localhost — the machine you are ru
 
 ### Testing services
 
-For testing services that require a service manager (like systemd), the default Docker images might not be enough. In this case, there is a collection of Docker images, with a service manager enabled, based on https://github.com/puppetlabs/litmusimage. For available images, see the [docker hub](https://hub.docker.com/u/litmusimage).
+For testing services that require a service manager (like systemd), the default Docker images might not be enough. In this case, there is a collection of Docker images, with a service manager enabled, based on our [litmus image repository](https://github.com/puppetlabs/litmusimage). For available images, see the [docker hub](https://hub.docker.com/u/litmusimage).
 
 Alternatively, you can use a dedicated VM that uses another provisioner, for example vmpooler or vagrant.
 
@@ -93,18 +94,18 @@ An example of a `provision.yaml` defining a single node:
 ---
 list_name:
   provisioner: vagrant
-  images: ['centos/7', 'generic/ubuntu1804', 'gusztavvargadr/windows-server']
+  images: ['centos/stream9', 'generic/ubuntu2204', 'gusztavvargadr/windows-server']
   params:
     param_a: someone
     param_b: something
 ```
 
 Take note of the following:
 
-- The `list_name` is arbitrary and can be any string you want.
-- The `provisioner` specifies which provision task to use.
-- The `images` must specify an array of one or more images to provision.
-- Any keys inside of `params` will be turned into process-scope environment variables as the key, upcased. In the example above, `param_a` would become an environment variable called `PARAM_A` with a value of `someone`.
+* The `list_name` is arbitrary and can be any string you want.
+* The `provisioner` specifies which provision task to use.
+* The `images` must specify an array of one or more images to provision.
+* Any keys inside of `params` will be turned into process-scope environment variables as the key, upcased. In the example above, `param_a` would become an environment variable called `PARAM_A` with a value of `someone`.
 
 An example of a `provision.yaml` defining multiple nodes:
 
@@ -113,16 +114,16 @@ An example of a `provision.yaml` defining multiple nodes:
 ---
 default:
   provisioner: docker
-  images: ['litmusimage/centos:7']
+  images: ['litmusimage/centos:stream9']
 vagrant:
   provisioner: vagrant
-  images: ['centos/7', 'generic/ubuntu1804', 'gusztavvargadr/windows-server']
+  images: ['centos/stream9', 'generic/ubuntu2204', 'gusztavvargadr/windows-server']
 docker_deb:
   provisioner: docker
-  images: ['litmusimage/debian:8', 'litmusimage/debian:9', 'litmusimage/debian:10']
+  images: ['litmusimage/debian:10', 'litmusimage/debian:11', 'litmusimage/debian:12']
 docker_ub:
   provisioner: docker
-  images: ['litmusimage/ubuntu:14.04', 'litmusimage/ubuntu:16.04', 'litmusimage/ubuntu:18.04']
+  images: ['litmusimage/ubuntu:18.04', 'litmusimage/ubuntu:20.04', 'litmusimage/ubuntu:22.04']
 docker_el6:
   provisioner: docker
   images: ['litmusimage/centos:6', 'litmusimage/oraclelinux:6', 'litmusimage/scientificlinux:6']
@@ -155,15 +156,15 @@ Use the following command to install an agent on a single target or on all the t
 
 Install an agent on a target using the following commands:
 
-```
+```bash
 # Install the latest Puppet agent on a specific target
 pdk bundle exec rake 'litmus:install_agent[gn55owqktvej9fp.delivery.puppetlabs.net]'
 
 # Install the latest Puppet agent on all targets
 pdk bundle exec rake "litmus:install_agent"
 
-# Install Puppet 5 on all targets
-pdk bundle exec rake 'litmus:install_agent[puppet5]'
+# Install Puppet 8 on all targets
+pdk bundle exec rake 'litmus:install_agent[puppet8-nightly]'
 
 ```
 
@@ -175,13 +176,13 @@ Using PDK and Bolt, the `rake litmus:install_module` command builds and installs
 
 For example:
 
-```
+```bash
 pdk bundle exec rake "litmus:install_module"
 ```
 
 If you need multiple modules on the target system (e.g. fixtures pulled down through `pdk bundle exec rake spec_prep`, or a previous unit test run):
 
-```
+```bash
 pdk bundle exec rake "litmus:install_modules_from_directory[spec/fixtures/modules]"
 ```
 
@@ -192,41 +193,48 @@ pdk bundle exec rake "litmus:install_modules_from_directory[spec/fixtures/module
 There are several options for running tests. Litmus primarily uses [serverspec](https://serverspec.org/), though you can use other testing tools.
 
 When running tests with Litmus, you can:
+
 * Run all tests against a single target.
 * Run all tests against all targets in parallel.
 * Run a single test against a single target.
 
 An example running all tests against a single target:
 
-```
+```bash
 # On Linux/MacOS:
 TARGET_HOST=lk8g530gzpjxogh.delivery.puppetlabs.net pdk bundle exec rspec ./spec/acceptance
 TARGET_HOST=localhost:2223 pdk bundle exec rspec ./spec/acceptance
+```
+
+```powershell
 # On Windows:
 $ENV:TARGET_HOST = 'lk8g530gzpjxogh.delivery.puppetlabs.net'
 pdk bundle exec rspec ./spec/acceptance
 ```
 
 An example running a specific test against a single target:
 
-```
+```bash
 # On Linux/MacOS:
 TARGET_HOST=lk8g530gzpjxogh.delivery.puppetlabs.net pdk bundle exec rspec ./spec/acceptance/test_spec.rb:21
 TARGET_HOST=localhost:2223 pdk bundle exec rspec ./spec/acceptance/test_spec.rb:21
+```
+
+```powershell
 # On Windows:
 $ENV:TARGET_HOST = 'lk8g530gzpjxogh.delivery.puppetlabs.net'
 pdk bundle exec rspec ./spec/acceptance/test_spec.rb:21
 ```
 
 An example running all tests against all targets, as specified in the `spec/fixtures/litmus_inventory.yaml` file:
 
-```
+```bash
 pdk bundle exec rake litmus:acceptance:parallel
 ```
 
 An example running all tests against localhost. Note that this is only recommended if you are familiar with the code base, as tests may have unexpected side effects on your local machine.
 
-```
+```bash
 pdk bundle exec rake litmus:acceptance:localhost
 ```
 
@@ -238,7 +246,7 @@ For more test examples, see [run_tests task](https://github.com/puppetlabs/provi
 
 Use the commands below to clean up provisioned systems after running tests. Specify whether to to remove an individual target or all the targets in the `spec/fixtures/litmus_inventory.yaml` file.
 
-```
+```bash
 # Tear down a specific target vm
 pdk bundle exec rake "litmus:tear_down[c985f9svvvu95nv.delivery.puppetlabs.net]"
 

docs/md/content/usage/litmus-helper-functions.md

@@ -6,6 +6,6 @@ description: Learn all about Litmus functions.
 
 Inside of the Litmus gem, there are three distinct sets of functions:
 
-*  Rake tasks for the CLI that allows you to use the Litmus commands (provision, install an agent, install a module and run tests.). Run `pdk bundle exec rake -T` to get a list of available rake tasks.
+* Rake tasks for the CLI that allows you to use the Litmus commands (provision, install an agent, install a module and run tests.). Run `pdk bundle exec rake -T` to get a list of available rake tasks.
 * Helper functions for serverspec / test. These apply manifests or run shell commands. For more information, see [Puppet Helpers](https://www.rubydoc.info/gems/puppet_litmus/PuppetLitmus/PuppetHelpers)
 * Helper Functions for Bolt inventory file manipulation. For more information, see [Inventory Manipulation](https://www.rubydoc.info/gems/puppet_litmus/PuppetLitmus/InventoryManipulation).

docs/md/content/usage/testing/litmus-test-examples.md

@@ -88,4 +88,4 @@ gem  'pry-byebug', '> 3.4.3'
 
 ## Setting up Travis and Appveyor
 
-To see this running on CI, enable the `use_litmus` flags for Travis CI and/or Appveyor. See the [pdk-templates docs](https://github.com/puppetlabs/pdk-templates#travisyml) for details and additional options.
+To see this running on CI, enable the `use_litmus` flags for Travis CI and/or Appveyor.