Training¶

Overview¶

A introductory walk-through to codestream-cli using common command-line examples.

Prepare¶

This walk-through is based on the assumption that all commands will be run inside a temporary container. There several options for running codestream-cli, and if you are running under different conditions you will need to adjust the commands accordingly.

⚠️ NOTE:

If you don’t wish to run the container image interactively, another option is to use the container’s default entrypoint (codestream-cli) directly.

However if you choose this path, you will need to ensure that all the required environment variables are available either by using an env file or passing the correct flags to the cli before starting.

System Environment Variables¶

Set the following variables in your local shell. If you intend on using codestream-cli often, I suggest adding them to your personal dotfiles to avoid needing to do this each time.

# Container registry variables.
REGISTRY="ghcr.io"
IMAGE="salt-labs/containers/codestream-cli"
TAG="latest"
CONTAINER="${REGISTRY}/${IMAGE}:${TAG}"

# User variables
export CODESTREAM_CLI_VRA_URL="https://vmwareauto.saltlabs.cloud"
export CODESTREAM_CLI_VRA_USERNAME="put_username_here"

# Optional user variables if you want to increase logging.
export CODESTREAM_CLI_LOG_LEVEL="DEBUG"
export CODESTREAM_CLI_LOG_FILE="codestream-cli.log"

# A shortcut if you decide to use the entrypoint directly.
CODESTREAM_CLI_COMMAND="docker container run --name codestream-cli --rm --env-file .env ${CONTAINER}"

Container¶

If you haven’t already, make sure you are logged into the registry before continuing.

docker login ${REGISTRY}

Ensure you can pull the codestream-cli container image locally before continuing.

docker image pull ${CONTAINER}

Container Environment Variables¶

In order to make the process repeatable for subsequent container launches, it is suggested that you create a reusable env file. This allows you to pass through your local environment variables you set previously into the container each launch time.

⚠️ NOTE: You have 2 options here depending on you’re desired setup.

Option 1. You can set the values for the variables you desire directly in .env file with the format VARIABLE=VALUE. This file is then read by the docker command.

If you only intend to run the container as a user, this is the recommended approach.

# Example that sets the values directly inside the .env file
cat <<-EOF > .env

CODESTREAM_CLI_LOG_LEVEL="INFO"
CODESTREAM_CLI_VRA_URL="https://vmwareauto.saltlabs.cloud"

EOF

Option 2. You can set the values for the variables in your local system’s dotfiles and pass them through with the format VARIABLE.

If you intend to run the container as a user but also perform local development of codestream-cli this is the recommended approach.

# Example setup of local dotfiles
cat <<- EOF >> ${HOME}/.bashrc

# codestream-cli
export CODESTREAM_CLI_LOG_LEVEL="INFO"
export CODESTREAM_CLI_VRA_URL="https://vmwareauto.saltlabs.cloud"

EOF

# Example that passes local values inside the container.
cat <<-EOF > .env

CODESTREAM_CLI_LOG_LEVEL
CODESTREAM_CLI_VRA_URL

EOF

You can mix and match depending on you’re local system setup.

The below full example has already setup the variables in the local system dotfiles and passes the majority through from the local system into the container (this was option 2 above).

You will note the example of the log file location has been overridden to be accessible in the current directory inside the container.

cat <<-EOF > .env

# This defaults to INFO, but the following are valid. DEBUG, INFO, WARNING, ERROR
CODESTREAM_CLI_LOG_LEVEL

# If not set, will write all logs to stdout.
CODESTREAM_CLI_LOG_FILE=codestream-cli.log

# Set this to true for additional debug information.
CODESTREAM_CLI_TRACE_ENABLED

# Set to true to ignore certificate errors.
CODESTREAM_CLI_SKIP_VERIFY_CERTS

# Set this to the vRA URL if you don't want to have to do --url for all commands.
CODESTREAM_CLI_VRA_URL

# The credentials to login to vRA
CODESTREAM_CLI_VRA_USERNAME
CODESTREAM_CLI_VRA_PASSWORD

# If you already have a token, you can pass it into the container.
CODESTREAM_CLI_VRA_TOKEN

# A timeout in seconds to wait for the vRA API. Defaults to 3 if not defined.
CODESTREAM_CLI_VRA_TIMEOUT

EOF

Start a temporary container image.

docker container run --rm --name codestream-cli -it --env-file .env --entrypoint /bin/bash "${CONTAINER}"

⚠️ NOTE: All commands from this point are to be run within the container environment unless otherwise specified.

Examples¶

The following are common examples for working with codestream-cli. Additional subcommands can be found looking at the full documentation.

Each example is meant to act as a guide, showing you where to find the correct syntax from the in-built help.

If you are lazy or get stuck, see the Answer sections included in each example.

Tokens¶

To work with the vRA API, you first need to obtain a refresh token. This is a long-lived token that is then used to obtain short-lived bearer tokens dynamically with each command. These bearer token are required to work with the API.

Refresh Token¶

Determine the correct command to obtain a refresh token by providing your vRA username and password.

# Show help
codestream-cli token --help

# Run you command here...

# TIP: If you're password contains special characters you will need to escape them or you can leave of the password input to be prompted to type it manually.

# Put your captured token into a variable for later use.
CODESTREAM_CLI_VRA_TOKEN="token_goes_here"

Answer

CODESTREAM_CLI_VRA_TOKEN=$(\
codestream-cli \
    token \
        --refresh-token \
            --username ${CODESTREAM_CLI_VRA_USERNAME:-EMPTY} \
            --password ${CODESTREAM_CLI_VRA_PASSWORD:-EMPTY} \
)

# Confirm you have captured a valid looking token before continuing.
echo ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY}

Bearer Token¶

This next example is not used very frequently (and is mostly only used for debugging auth issues). Figure out the command to obtain a bearer token using you’re existing refresh token.

# Show help
codestream-cli token --help

# Run your command here...

Answer

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    token \
        --bearer-token

Pipelines¶

Sample¶

Write this simple Code Stream Pipeline sample to a file. This will be used for subsequent commands.

cat <<-EOF > codestream.yaml
---

kind: PIPELINE

project: P-Tristram-DEV
name: codestream-cli_test_${CODESTREAM_CLI_VRA_USERNAME:-unknown}
icon: lightbulb,down, is-warning
enabled: false
description: |-
  A dummy pipeline for testing codestream-cli.
concurrency: 1

input:
  deployment_name: codestream-cli_test_${CODESTREAM_CLI_VRA_USERNAME:-unknown}
  vra_url: https://vmwareauto.saltlabs.cloud

_inputMeta:
  deployment_name:
    description: The name of the deployment to check for.
    mandatory: true
  vra_url:
    description: The URL of the vRA instance.
    mandatory: true

workspace:
  type: DOCKER
  endpoint: ''
  image: ''
  registry: Artifactory
  path: ''
  autoCloneForTrigger: false
  limits:
    cpu: 1.0
    memory: 512

stageOrder:

  - check

stages:

  check:

    taskOrder:

      - get_token

    tasks:

      get_token:
        type: Pipeline
        input:
          pipeline: vra_get_token
          inputProperties:
            API_Token: \${var.vra_api_token}
            vra_url: \${input.vra_url}

EOF

Validate¶

Determine the correct command to validate the pipeline file to check the syntax looks correct.

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

codestream-cli \
    pipelines \
        --validate-pipeline \
            --file codestream.yaml

Check (doesn’t exist)¶

Determine the correct command to check that an existing pipeline using that name doesn’t already exist in vRA.

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --check-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Import¶

Determine the correct command to import the pipeline using the file created earlier.

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --import-pipeline \
            --file codestream.yaml

Check (exists)¶

Determine the correct command to check that the pipeline now does exist in vRA

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --check-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Update¶

Make a change to the pipeline file and determine the correct command to import it again to update the pipeline.

# Show help
codestream-cli pipelines --help

# Example change to update the description.
sed -i "s/  A dummy pipeline for testing codestream-cli./  A dummy pipeline (now updated) for testing codestream-cli./g" codestream.yaml

# Run your command here...

# Verify the change in the UI
gio open ${CODESTREAM_CLI_VRA_URL:-EMPTY}

Answer

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --import-pipeline \
            --file codestream.yaml

Export (on-screen)¶

Determine the correct command to export the pipeline on-screen

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --export-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Export (to file)¶

Determine the correct command to export the same pipeline to a file.

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --export-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY} \
            --file pipeline_export.yaml

Get Info¶

Determine the correct command to get information about the existing pipeline in vRA.

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-info \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Get Id¶

Determine the correct command to obtain just the id for the existing pipeline in vRA.

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-id \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Get the execution ids for the existing pipeline (shouldn’t be any yet)

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-executions \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Determine the correct command to enable the pipeline for executions

# Show help
codestream-cli pipelines --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --enable-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Determine the correct command to execute the pipeline.

# Show help
codestream-cli pipeline --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-} \
    pipelines \
        --execute-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

# Here is an example if you wanted to provide additional inputs.
PIPELINE_INPUTS=$(cat <<EOF
{
    "deployment_name": "",
}
EOF
)
codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --execute-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY} \
            --inputs ${PIPELINE_INPUTS[@]}

Determine the correct command to get execution ids for the existing pipeline (should work now)

# Show help
codestream-cli pipeline --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-executions \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Determine the correct command to delete the pipeline

# Show help
codestream-cli pipeline --help

# Run your command here...

Answer

PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

# This example deletes the pipeline
codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --delete-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

Deployments¶

TODO: Complete this section when the subcommand is ready…

Blueprints¶

TODO: Complete this section when the subcommand is ready…

End¶

Exit the container image when you have finished.

exit