Skip to main content

Managing Releases with the CLI

This tutorial helps you use Replicated app manager to quickly deploy, install, and iterate with a sample Kubernetes application using a CLI-based workflow.

For a more conceptual overview before using the CLI tools, you can start with the tutorial for installing a sample application without an existing cluster.

To deploy the sample application, follow these steps:

  1. Install the replicated CLI
  2. Set a service account token
  3. Get YAML manifest files
  4. Create a release
  5. Create a customer license
  6. Get an installation command
  7. Install the app manager
  8. Install the application
  9. View the deployed application
  10. Iterate the application
  11. Update the test server

Install the replicated CLI

Install the replicated CLI to perform the deployment tasks.

To install the replicated CLI:

  1. Use homebrew or the latest Linux or macOS version from the replicatedhq/replicated releases page to install the CLI.

    brew install replicatedhq/replicated/cli
  2. Verify the installation using replicated version:

    $ replicated version
    {
    "version": "0.31.0",
    "git": "c67210a",
    "buildTime": "2020-09-03T18:31:11Z",
    "go": {
    "version": "go1.14.7",
    "compiler": "gc",
    "os": "darwin",
    "arch": "amd64"
    }
    }

Set a Service Account Token

Set up two environment variables for the application. You can export these in your shell or add them to your favorite dotfiles.

To export the environment variables:

  1. Log in to the Replicated vendor portal. Create a new application or use an existing application that you created previously. For this tutorial, we are using the name CLI Quickstart, although you can use any name.

  2. Open the Settings page. Copy the application slug.

    app-slug

  3. Run the following command using the application slug that you copied previously:

    export REPLICATED_APP=cli-quickstart
  4. Create a read/write capable service account token:

    service-account-token

  5. Run the following command to export the token:

    export REPLICATED_API_TOKEN=1366be611e3bf...
  6. Run the following command to verify these values are set correctly:

    replicated release ls

    You will likely see an empty list of releases. You will create a release later in this tutorial.

    SEQUENCE    CREATED    EDITED    ACTIVE_CHANNELS

Get YAML Manifest Files

YAML manifest files are needed to create a release. You can download a sample repository to get YAML files for this tutorial at https://github.com/replicatedhq/replicated-starter-kots.

note

If you are using Helm charts to package your application, you can explore Creating a release from an existing Helm chart for steps on how to add the required app manager YAML files to your Helm chart after you finish reviewing this tutorial.

To get the sample YAML files:

  1. Run the following command to create a folder for your project:

    mkdir replicated-cli-tutorial
    cd replicated-cli-tutorial
  2. Run the following command to make a folder for the manifests and download the starter YAML to it:

    mkdir ./manifests
    curl -fSsL https://github.com/replicatedhq/kots-default-yaml/archive/v2020-09-03.tar.gz | \
    tar xzv --strip-components=1 -C ./manifests \
    --exclude README.md --exclude LICENSE --exclude .gitignore

Verify the Manifest Files

You should now have a few YAML files in the manifests folder:

Example:

$ ls -la manifests
.rw-r--r-- 114 dex 16 Aug 7:59 config-map.yaml
.rw-r--r-- 906 dex 16 Aug 7:59 config.yaml
.rw-r--r-- 608 dex 16 Aug 7:59 deployment.yaml
.rw-r--r-- 296 dex 16 Aug 7:59 ingress.yaml
.rw-r--r-- 2.5k dex 16 Aug 7:59 preflight.yaml
.rw-r--r-- 399 dex 16 Aug 7:59 replicated-app.yaml
.rw-r--r-- 205 dex 16 Aug 7:59 service.yaml
.rw-r--r-- 355 dex 16 Aug 7:59 support-bundle.yaml

Run the following command to verify this YAML:

$ replicated release lint --yaml-dir=manifests

If there are no errors, an empty list is displayed with a zero exit code.

Example output:

RULE    TYPE    FILENAME    LINE    MESSAGE

Initialize the Repository

If you have not already done so, initialize this project as a git repository so that you can track your history. Additionally, the replicated CLI reads git metadata to help with the generation of release metadata, such as version labels. More information about this is covered later in this tutorial.

To initialize the repository, run the following commands:

git init
git add .
git commit -m "Initial Commit: CLI Quickstart"

Create a First Release

Now that you have some YAML manifest files, you can create a release and promote it to the Unstable channel for internal testing.

To create and promote a release:

  1. Run the following command with the --auto flag to generate release notes and metadata based on the git status.

    $ replicated release create --auto

    Example output:

        โ€ข Reading Environment โœ“  

    Prepared to create release with defaults:

    yaml-dir "./manifests"
    promote "Unstable"
    version "Unstable-ba710e5"
    release-notes "CLI release of master triggered by dex [SHA: ba710e5] [28 Sep 20 09:15 CDT]"
    ensure-channel true

    Create with these properties? [Y/n]
  2. Press Enter to confirm the prompt. The release is created and promoted.

    Example output:

      โ€ข Reading manifests from ./manifests โœ“  
    โ€ข Creating Release โœ“
    โ€ข SEQUENCE: 1
    โ€ข Promoting โœ“
    โ€ข Channel VEr0nhJBBUdaWpPvOIK-SOryKZEwa3Mg successfully set to release 1
  3. Run the following command to verify that the release was created:

    $ replicated release ls

    Example output:

    SEQUENCE    CREATED                      EDITED                  ACTIVE_CHANNELS
    1 2020-09-03T11:48:45-07:00 0001-01-01T00:00:00Z Unstable

Create a Customer License

After creating a release, you must create a customer object. A customer represents a single licensed end user of your application.

In this example, create a customer named Some Big Bank with an expiration in 10 days.

To create a customer license:

  1. Run the following command to create the customer and assign them to a channel. For this example, since you created your release on the Unstable channel, assign the customer to the same channel:

    replicated customer create \
    --name "Some-Big-Bank" \
    --expires-in "240h" \
    --channel "Unstable"

    Example output:

    ID                             NAME             CHANNELS     EXPIRES                          TYPE
    1h0yojS7MmpAUcZk8ekt7gn0M4q Some-Big-Bank Unstable 2020-09-13 19:48:00 +0000 UTC dev
  2. Run the following command to verify the customer creation details:

    replicated customer ls
  3. Run the following command to download a license file:

    replicated customer download-license \
    --customer "Some-Big-Bank"
  4. Because the license downloads to stdout, run the following command if you want to redirect the output to a file:

    export LICENSE_FILE=~/Desktop/Some-Big-Bank-${REPLICATED_APP}-license.yaml
    replicated customer download-license --customer "Some-Big-Bank" > "${LICENSE_FILE}"
  5. Verify the license was written properly using either cat or head:

    $ head ${LICENSE_FILE}

    apiVersion: kots.io/v1beta1
    kind: License
    metadata:
    name: some-big-bank
    spec:
    appSlug: kots-dex
    channelName: Unstable
    customerName: Some-Big-Bank
    endpoint: https://replicated.app

Get an Installation Command

After you create and download a customer license, get the installation commands so that you can test the installation on a development server.

Run the following command to get the installation commands for the Unstable channel:

$ replicated channel inspect Unstable

Example output:

ID:             VEr0nhJBBUdaWpPaOIK-SOryKZEwa3Mg
NAME: Unstable
DESCRIPTION:
RELEASE: 1
VERSION: Unstable-ba710e5
EXISTING:

curl -fsSL https://kots.io/install | bash
kubectl kots install cli-quickstart/unstable

EMBEDDED:

curl -fsSL https://k8s.kurl.sh/cli-quickstart-unstable | sudo bash

AIRGAP:

curl -fSL -o cli-quickstart-unstable.tar.gz https://k8s.kurl.sh/bundle/cli-quickstart-unstable.tar.gz
# ... scp or sneakernet cli-quickstart-unstable.tar.gz to airgapped machine, then
tar xvf cli-quickstart-unstable.tar.gz
sudo bash ./install.sh airgap

The output generates commands for installing on an existing cluster, installing without an existing cluster, and installing on an air gap cluster.

Install the App Manager

In this case, we demonstrate an installation without an existing cluster, on a single virtual machine (VM). This type of installation is known as an embedded or Kubernetes installer-created cluster.

To install the app manager:

  1. Create a server using Google Cloud using the following criteria for this example:

    • Ubuntu 18.04
    • At least 8 GB of RAM
    • 4 CPU cores
    • At least 40GB of disk space
    note

    You can use any cloud provider or local virtual machine.

  2. Use SSH to access the server you just created, and run the installation script from above, using the EMBEDDED version:

    curl -sSL https://kurl.sh/<your-app-name-and-channel> | sudo bash

    This script installs Docker, Kubernetes, and the Replicated admin console containers (kotsadm).

    Installation takes approximately 5-10 minutes.

    After the script completes the initial installation, the output displays the connection URL and password that you must use in a later step of the installation process:


    Kotsadm: http://[ip-address]:8800
    Login with password (will not be shown again): [password]
  3. Reload your shell using the following command to access the cluster with kubectl:

    bash -l

    The UIs of Prometheus, Grafana and Alertmanager have been exposed on NodePorts 30900, 30902 and 30903 respectively.

  4. Use the generated user:password of admin:[password] to access Grafana.

  5. Run the following script on your other nodes to add worker nodes to this installation:

    curl -sSL https://kurl.sh/cli-quickstart-unstable/join.sh | sudo bash -s kubernetes-master-address=[ip-address]:6443 kubeadm-token=[token] kubeadm-token-ca-hash=sha256:[sha] kubernetes-version=1.16.4 docker-registry-ip=[ip-address]
  6. Reload the shell, following the instructions on the screen, to make kubectl work:

    [email protected]:~$ kubectl get pods

    Example output:

    NAME                                  READY   STATUS      RESTARTS   AGE
    kotsadm-585579b884-v4s8m 1/1 Running 0 4m47s
    kotsadm-migrations 0/1 Completed 2 4m47s
    kotsadm-operator-fd9d5d5d7-8rrqg 1/1 Running 0 4m47s
    kotsadm-postgres-0 1/1 Running 0 4m47s
    kurl-proxy-kotsadm-77c59cddc5-qs5bm 1/1 Running 0 4m46s
    [email protected]:~$

Install the Application

At this point, Kubernetes and the Replicated admin console are running, but the application is not deployed yet.

To install the application:

  1. In a browser, enter the URL that the installation script displayed previously when it finished. Notice that the app manager cluster, created using the Kubernetes installer, has provisioned a self-signed certificate.

    When you bypass the insecure certificate warning, you have the option of uploading a trusted certificate and key. For production installations, we recommend using a trusted certificate. For this tutorial, use the self-signed certificate.

  2. Click Skip & continue to proceed using the self-signed certificate.

    Console TLS

    You are prompted for a password.

  3. Enter the password from the CLI output to log in to the admin console.

    The Upload license page opens. Until this point, this server is running Docker, Kubernetes, and the admin console containers only.

  4. Click Upload. Select your YAML license file or drag and drop the license file from your desktop. The admin console can pull containers and run your application now.

    The Settings page opens with default configuration items.

  5. If you are using the defaults, select the Enable Ingress checkbox. You can leave the Ingress Hostname field blank. Click Continue.

    note

    For production, you can customize this screen to collect the configuration that your application needs from the customer.

    Settings Page

    The Preflight page opens.

  6. Click Continue. If there are failing checks, dismiss the warning to continue. Preflight checks are designed to help ensure this server has the minimum system and software requirements to run the application. Depending on your YAML configuration in preflight.yaml, you can see some of the example preflight checks fail.

    Vendors can optionally configure strict preflight checks that cause the application deployment to fail if specific requirements are not met. For more information about preflight checks, see Creating Preflight Checks and Support Bundles.

    Additionally, when installing with minimal role-based access control (RBAC), the preflight checks can fail due to insufficient privileges.

    Run Preflight Checks Manually

    When this occurs, a kubectl preflight command is displayed that lets the end user manually run the preflight checks and upload the results automatically to the app manager. For more information about configuring RBAC privileges, see requireMinimalRBACPrivileges and supportMinimalRBACPrivileges in the Application custom resource.

    After the preflight checks pass, the Version History page opens and displays the initial version that was deployed. Later, you will come back to this page to deploy an update to the application.

  7. Click Application on the top to see the status of the application and some basic monitoring statistics (such as CPU, memory, and disk space). If you are still connected to this server using SSH, kubectl get pods shows the example NGINX service that you just deployed.

    Cluster

View the Deployed Application

Since you used the default NGINX application and enabled the Ingress object, you can view the application at http://${INSTANCE_IP}/ without a port and see a basic NGINX server running:

Cluster

Next, you will create and deliver an update to the sample application.

Iterate the Application

From your local repo, you can update the NGINX deployment to test a simple update to the application.

To make an update:

  1. Add the following line to deployment.yaml, right after spec::

      replicas: 2
  2. Use head to view the first 10 lines of the file:

    head manifests/deployment.yaml

    Example output:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: example-nginx
    labels:
    app: example
    component: nginx
    spec:
    replicas: 2
    selector:
  3. Run the following command to create a new release:

    replicated release create --auto

Update the Test Server

To install and test this new release, you must connect to the admin console on port :8800 using a web browser. At this point, the UI likely shows that your test application is up-to-date and that no updates are available. The admin console can be configured to check for new updates at regular intervals, but for now you will trigger a check manually.

To check for updates manually:

  1. Click Check for Updates on the Version History page. You should see a new release in the history now. You can click Diff versions to review the differences.

    View Update

  2. Click Deploy to apply the new YAML, which changes the number of NGINX replicas. The deployment only takes a few seconds.

  3. Run the following command to verify the deployment on the server:

    kubectl get pod -l component=nginx

    You should see two pods running.

Next Steps

You can iterate further on your application. Continue making changes and using replicated release create --auto to publish them. You can add -y to the command to skip the prompt.

To learn more about the app manager features, you can explore some of the tutorials and packaging options, such as:

If you already have a release published in the vendor portal that you want to use as a starting point, run the following command to access the help docs for replicated release download:

replicated release download --help