Merge pull request #94 from cyberark/72-add-example-applications

Adds example for deploying applications on KinD cluster

Author: diverdane

conjur-oss/README.md

@@ -31,6 +31,7 @@ Conjur Open Source is part of the CyberArk Privileged Access Security Solution w
   * [Deploying Without LoadBalancer Support (e.g. for KinD, MiniKube, KataCoda)](#deploying-without-loadbalancer-support-eg-for-kind-minikube-katacoda)
   * [Debugging](#debugging)
   * [PostgreSQL Database Password Restrictions](#postgresql-database-password-restrictions)
+- [What's Next? Deploy an Example Application That Uses Conjur Secrets](#whats-next-deploy-an-example-application-that-uses-conjur-secrets)
 - [Deleting the Conjur Deployment](#deleting-the-conjur-deployment)
   * [Uninstalling the Chart via Helm Delete](#uninstalling-the-chart-via-helm-delete)
   * [Cleaning Up Kubernetes Secrets Not Managed by Helm](#cleaning-up-kubernetes-secrets-not-managed-by-helm)
@@ -200,7 +201,7 @@ container to create an account during startup. To retrieve the credentials
 for this account, perform the following commands:
 
 ```sh-session
-ACCOUNT_NAME=<conjur-account-name>
+CONJUR_ACCOUNT=<conjur-account-name>
 CONJUR_NAMESPACE=<conjur-namespace>
 HELM_RELEASE=<helm-release>
 POD_NAME=$(kubectl get pods --namespace "$CONJUR_NAMESPACE" \
@@ -209,7 +210,7 @@ POD_NAME=$(kubectl get pods --namespace "$CONJUR_NAMESPACE" \
 kubectl exec --namespace "$CONJUR_NAMESPACE" \
             "$POD_NAME" \
             --container=conjur-oss \
-            -- conjurctl role retrieve-key "$ACCOUNT_NAME":user:admin | tail -1
+            -- conjurctl role retrieve-key "$CONJUR_ACCOUNT":user:admin | tail -1
 ```
 
 > Note: If you have `logLevel` set to `debug`, the `tail -1` command will truncate the output.
@@ -219,14 +220,14 @@ If you set `account.create` to `false`, or did not provide a value, an admin acc
 need to be created. To create an account, use the following commands:
 
 ```sh-session
-ACCOUNT_NAME=<Name for Conjur account to be created>
+CONJUR_ACCOUNT=<Name for Conjur account to be created>
 POD_NAME=$(kubectl get pods --namespace "$CONJUR_NAMESPACE" \
             -l "app=conjur-oss,release=$HELM_RELEASE" \
             -o jsonpath="{.items[0].metadata.name}")
 kubectl exec --namespace $CONJUR_NAMESPACE \
               $POD_NAME \
               --container=conjur-oss \
-              -- conjurctl account create $ACCOUNT_NAME | tail -1
+              -- conjurctl account create $CONJUR_ACCOUNT | tail -1
 ```
 The credentials for this account will be provided after the account has been created.
 Store these in a safe location.
@@ -452,6 +453,40 @@ The following restrictions apply to the PostgreSQL database password:
     ["-", ".", "_", or "~"]
 - Password length must be less than or equal to 64 characters.
 
+## What's Next? Deploy an Example Application That Uses Conjur Secrets
+
+If you are new to Conjur, you may be interested in learning more about how
+Conjur security policy can be configured and an application can
+be deployed that uses Conjur OSS to safely manage secrets data.
+
+This repository contains a set of scripts that can:
+
+- Create a [Kubernetes-in-Docker](https://github.com/kubernetes-sigs/kind)
+  (KinD) cluster on your local machine
+- Helm install a Conjur OSS cluster on that KinD cluster
+- Enable the
+  [Conjur Kubernetes Authenticator](https://docs.conjur.org/Latest/en/Content/Operations/Services/k8s_auth.htm)
+  (authn-k8s) (as a security admin)
+- Load Conjur security policies for some example applications
+  (as a security admin)
+- Deploy instances of a simple "Pet Store" application each using
+  one of the following Conjur authentication broker/clients:
+  - [Secretless Broker](https://github.com/cyberark/secretless-broker) sidecar container
+  - [Conjur Kubernetes Authenticator Client](https://github.com/cyberark/conjur-authn-k8s-client)
+    sidecar container
+  - [Conjur Kubernetes Authenticator Client](https://github.com/cyberark/conjur-authn-k8s-client)
+    init container
+  (as an application developer/deployer)
+
+Please refer to the [README.md](../examples/kubernetes-in-docker/README.md)
+file in the `../examples/kubernetes-in-docker` directory for more details
+on how to run these demo scripts.
+
+These scripts will also generate some application-specific Conjur policy
+YAML files and Kubernetes application manifests as concrete examples of
+how applications can be deployed that use Conjur Kubernetes authentication
+to safely retrieve secrets.
+
 ## Deleting the Conjur Deployment
 
 Uninstalling or deleting a Conjur deployment involves two steps:

examples/kubernetes-in-docker/0_export_env_vars.sh

@@ -0,0 +1,33 @@
+# KinD and Helm install options
+export CREATE_KIND_CLUSTER="${CREATE_KIND_CLUSTER:-true}"
+export KIND_CLUSTER_NAME="${KIND_CLUSTER_NAME:-kind}"
+export HELM_INSTALL_CONJUR="${HELM_INSTALL_CONJUR:-true}"
+export HELM_RELEASE="${HELM_RELEASE:-conjur-oss}"
+export CONJUR_NAMESPACE="${CONJUR_NAMESPACE:-conjur-oss}"
+export CONJUR_ACCOUNT="${CONJUR_ACCOUNT:-myConjurAccount}"
+export CONJUR_LOG_LEVEL="${CONJUR_LOG_LEVEL:-info}"
+
+# Basic demo config
+export TEST_APP_DATABASE="${TEST_APP_DATABASE:-postgres}"
+export TEST_APP_NAMESPACE_NAME="${TEST_APP_NAMESPACE_NAME:-app-test}"
+
+# Configuration for Conjur authn-k8s
+export ANNOTATION_BASED_AUTHN="${ANNOTATION_BASED_AUTHN:-true}"
+export AUTHENTICATOR_ID="${AUTHENTICATOR_ID:-my-authenticator-id}"
+
+# Conjur OSS Helm chart specific setting for demo scripts
+export CONJUR_OSS_HELM_INSTALLED="${CONJUR_OSS_HELM_INSTALLED:-true}"
+
+# KinD specific specific setting for demo scripts
+export TEST_APP_LOADBALANCER_SVCS="${TEST_APP_LOADBALANCER_SVCS:-false}"
+
+# DockerHub account credentials are required since the demo scripts need to
+# build and push demo images to a registry so that the images can then be
+# pulled by KinD.
+#
+# These should be configured/customized in bootstrap.env
+check_env_var "DOCKER_REGISTRY_URL"
+check_env_var "DOCKER_REGISTRY_PATH"
+check_env_var "DOCKER_USERNAME"
+check_env_var "DOCKER_PASSWORD"
+check_env_var "DOCKER_EMAIL"

examples/kubernetes-in-docker/1_create_kind_cluster.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+set -euo pipefail
+
+. utils.sh
+
+check_env_var "KIND_CLUSTER_NAME"
+min_kind_version="0.7.0"
+
+# Confirm that 'kind' binary is installed.
+if ! command -v kind &> /dev/null; then
+  echo "kind binary not found. See https://kind.sigs.k8s.io/docs/user/quick-start/"
+  echo "for installation instructions."
+  exit 1
+fi
+
+# Check version of 'kind' binary.
+kind_version="$(kind version -q)"
+if ! meets_min_version $kind_version $min_kind_version; then
+  echo "kind version $kind_version is invalid. Version must be $min_kind_version or newer"
+  exit 1
+fi
+
+# Check if KinD cluster has already been created
+if [ "$(kind get clusters | grep "^$KIND_CLUSTER_NAME$")" = "$KIND_CLUSTER_NAME" ]; then
+  echo "KinD cluster '$KIND_CLUSTER_NAME' already exists. Skipping cluster creation."
+else
+  kind create cluster --name "$KIND_CLUSTER_NAME"
+fi

examples/kubernetes-in-docker/2_helm_install_or_upgrade_conjur.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+. utils.sh
+
+min_helm_version="3.1"
+
+# Confirm that 'helm' binary is installed.
+if ! command -v helm &> /dev/null; then
+  echo "helm binary not found. See https://helm.sh/docs/intro/install/"
+  echo "for installation instructions."
+  exit 1
+fi
+
+# Check version of 'helm' binary.
+helm_version="$(helm version --template {{.Version}} | sed 's/^v//')"
+if ! meets_min_version $helm_version $min_helm_version; then
+  echo "helm version $helm_version is invalid. Version must be $min_helm_version or newer"
+  exit 1
+fi
+
+# Create the namespace for the Conjur cluster if necessary
+if has_namespace "$CONJUR_NAMESPACE"; then
+  echo "Namespace '$CONJUR_NAMESPACE' exists, not going to create it."
+else
+  kubectl create ns "$CONJUR_NAMESPACE"
+fi
+
+# Check if the Conjur cluster release has already been installed. If so, run
+# Helm upgrade. Otherwise, do a Helm install of the Conjur cluster.
+if [ "$(helm list -q -n $CONJUR_NAMESPACE | grep "^$HELM_RELEASE$")" = "$HELM_RELEASE" ]; then
+  helm upgrade \
+      -n "$CONJUR_NAMESPACE" \
+      --set account.name="$CONJUR_ACCOUNT" \
+      --set account.create="true" \
+      --set authenticators="authn\,authn-k8s/$AUTHENTICATOR_ID" \
+      --set logLevel="$CONJUR_LOG_LEVEL" \
+      --reuse-values \
+      --recreate-pods \
+      "$HELM_RELEASE" \
+      "../../conjur-oss"
+else
+  # Helm install a Conjur cluster and create a Conjur account
+  data_key="$(docker run --rm cyberark/conjur data-key generate)"
+  echo "data_key: $data_key"
+  helm install \
+      -n "$CONJUR_NAMESPACE" \
+      --set dataKey="$data_key" \
+      --set account.name="$CONJUR_ACCOUNT" \
+      --set account.create="true" \
+      --set authenticators="authn\,authn-k8s/$AUTHENTICATOR_ID" \
+      --set logLevel="$CONJUR_LOG_LEVEL" \
+      "$HELM_RELEASE" \
+      "../../conjur-oss"
+fi

examples/kubernetes-in-docker/3_retrieve_admin_password.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+set -euo pipefail
+
+. utils.sh
+
+master_pod="$(get_master_pod_name)"
+echo "$(kubectl exec \
+        -n "$CONJUR_NAMESPACE" \
+        "$master_pod" \
+        --container=conjur-oss \
+        -- conjurctl role retrieve-key "$CONJUR_ACCOUNT":user:admin | tail -1)"

examples/kubernetes-in-docker/4_ensure_authn_k8s_enabled.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+set -euo pipefail
+
+. utils.sh
+
+# Ensure that $AUTHENTICATOR_ID is enabled for authn-k8s
+authenticators="$(kubectl get secret \
+                  -n $CONJUR_NAMESPACE \
+                  $HELM_RELEASE-conjur-authenticators \
+                  --template={{.data.key}} | base64 -d)"
+if grep -q "$authenticators" <<< "$AUTHENTICATOR_ID"; then
+  echo "Enabling authenticator ID $AUTHENTICATOR_ID for authn-k8s"
+  helm upgrade \
+       -n "$CONJUR_NAMESPACE" \
+       --reuse-values \
+       --recreate-pods \
+       --set authenticators="authn\,authn-k8s/$AUTHENTICATOR_ID" \
+       --set logLevel="$CONJUR_LOG_LEVEL" \
+       "$HELM_RELEASE" \
+       ../../conjur-oss
+
+  # Pause to let Helm begin to terminate existing pods as a result
+  # of Helm upgrade
+  sleep 5
+
+  # Wait for Conjur master pod to have both containers ready
+  wait_for_conjur_ready
+
+else
+  echo "Authenticator ID $AUTHENTICATOR_ID is already enabled for authn-k8s"
+fi

examples/kubernetes-in-docker/5_deploy_demo_apps.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -euo pipefail
+
+. utils.sh
+
+conjur_demo_scripts_path="temp/kubernetes-conjur-demo"
+
+# Clone the conjurdemos/kubernetes-conjur-demo repo
+rm -rf "$conjur_demo_scripts_path"
+announce "Cloning Kubernetes Conjur Demo scripts to $conjur_demo_scripts_path"
+mkdir -p temp
+git clone https://github.com/conjurdemos/kubernetes-conjur-demo "$conjur_demo_scripts_path"
+
+# Because the kubernetes-conjur-demo scripts use a different naming convention
+# for the Conjur namespace env variable, some translation is required.
+export CONJUR_NAMESPACE_NAME="$CONJUR_NAMESPACE"
+
+announce "Running the Kubernetes Conjur Demo scripts"
+cd "$conjur_demo_scripts_path"
+./start