Project overview

The following is an excerpt from a public cloud installation guide for a SaaS product for Google, Amazon, Azure, and Vanilla Kubernetes clusters.

This guide transformed product installation. Before the guide, one of our developers spent a week on-site installing the product; after publishing the guide, clients installed the product independently with up to two hours of developer support by phone.

Docs-as-code toolchain

We used a docs-as-code toolchain to create this guide and all other technical, user, and developer documentation, specifically:

On this page

Guide introduction

Before you can start using redacted to redacted, you need to install it.

Installing redacted is a multi-step process:

  1. Before you begin, read the explanation of DNS entry format, PSPs, and minimum machine requirements [included in this sample]
  2. Prepare your Kubernetes cluster [included in this sample]
  3. Set up external connections
  4. Install your TLS certificate [included in this sample]
  5. Download the installer
  6. Configure your instance
  7. Install redacted
  8. Create your DNS entry

Installation prerequisites

Before you begin

Before getting into the installation process, review the following requirements:

  • Kubernetes compatibility
  • DNS entry format
  • PSP requirements
  • Minimum machine requirements

Kubernetes compatibility

This version of the redacted installer is compatible with Kubernetes versions 1.12 to 1.15.

DNS entry format

Your DNS entry must follow this pattern: prefix-suffix[.subdomain].domain.com. The entire entry must respect DNS norms according to RFC-1034.

IMPORTANT: You will not create your DNS zone until the end of the installation process.

Component Details Example
prefix 12 characters maximum
Only letters and numbers are allowed (no hyphens or special characters)
This might be your company name or a shortened version of your company name
suffix (Required) For redacted to function, your DNS entry must contain a suffix workspace
domain (Required) Company's domain to which your redacted platform will be connected dundermifflin.com
subdomain Optional Allowed as many subdomains after `prefix-suffix` as needed or as your company's policy requires paper

Sample URL: dunder-workspace.dundermifflin.com
Sample URL with subdomain: dunder-workspace.paper.dundermifflin.com

PSP requirements

Redacted deployment requires two Pod Security Policies (PSP).

The admission controller can be enabled or disabled:

Status Details
Disabled No effect on your cluster
Enabled now Redacted will run as expected
Enabled later Will not prevent redacted from running as expected

PSPs are applied to a Service Account through a ClusterRole and the related ClusterRoleBinding. PSPs and the related ClusterRole and ClusterRoleBinding are provided in the requirements.yml file that will be created later in the installation process.

Minimum machine requirements

Regardless of your cloud provider, you must meet these minimum machine requirements:

  • 3 nodes
  • 4 vCPU per node
  • 16 GB RAM per node
  • 300 GB distributed disk storage

Prepare Kubernetes cluster

This section will guide you through configuring your redacted-compatible Kubernetes cluster, regardless of cloud provider.

You will:

  1. Create and apply your requirements.yml file.
  2. Apply or install the secret redacted-docker-config.
  3. For offline clusters only, modify your Kubernetes cluster to meet offline specifications.

Create requirements

All redacted deployments need the same requirements.yml file, regardless of your cloud provider.

The requirements.yml file will create two service accounts on the redacted-common namespace:

  • sa-redacted-deploy with cluster-admin role
  • traefik-ingress-controller with its related ClusterRole and ClusterRoleBinding

Create requirements.yml file

Create your requirements.yml with the code exactly as it appears below.

The requirements.yml file appears here in the guide.

Apply requirements.yml file

Run the following command to apply your `requirements.yml` file:

kubectl apply -f requirements.yml

Apply or install secret redacted-docker-config

Redacted Docker images are pulled from a private registry that requires credentials. The credentials should have been provided to you.

Apply the secret

If you receive the credentials in a Kubernetes secret file, apply the secret to your cluster by running the following kubectl command:

kubectl apply -n redacted-common -f redacted-docker-config.yaml

Install the secret

If you receive a username and password, install the secret by running the following `kubectl` command:

kubectl create secret docker-registry -n redacted-common redacted-docker-config \
--docker-server={registry server} \ <1>
--docker-username={username} \ <2>
--docker-password={password} <3>

  1. Replace {registry server} with the Docker repository hosting redacted images.
  2. Replace {username} with the username provided to you.
  3. Replace {password} with the password provided to you.

Finally, edit the default service account to reference the `redacted-docker-config` secret by running the following `kubectl` command:

kubectl patch serviceaccount -n redacted-common default -p '{"imagePullSecrets":[{"name" : "redacted-docker-config"}]}'

Offline cluster specifications

When your Kubernetes cluster is not connected to the Internet, you'll install redacted in offline mode.

For offline installation, you need to manage your own Docker registry containing images of the redacted product as well as redacted technologies. This section of documentation will guide you through uploading the resources to your registry and installing the repository in your cluster.

IMPORTANT: Redacted will provide the archives of the Docker images needed to run your platform, as well as the technologies.

Upload Docker images

To upload the Docker images in your registry, you need:

  • A machine with access to your Docker registry
  • tar archives provided by redacted (product and technologies)
  • Command line tool skopeo installed on your machine (refer to Install Skopeo)
  • Credentials to push images into the registry (if any)

Upload redacted product archive

Once you meet these requirements, complete the following steps to upload your Docker images.

  1. First, run the following command to decompress the archive:
untar xvf {product-tar-archive} where {product-tar-archive} is the file name of the redacted product tar archive provided.
  1. Next, if you need to require authentication, configure the user and password to connect to your registry using skopeo login (refer to Skopeo login).
  2. Finally, run the following command in the decompressed archive to launch the image upload:
./pushall.sh {registry} where {registry} is the hostname of your Docker registry.

Upload redacted technologies archive

The process is the same as for the redacted technologies tar archive.

NOTE: If you configured authentication on this machine when uploading the first tar archive, you will not need to configure it again.

  1. Run the following command to decompress the archive:
untar xvf {technologies-tar-archive} where {technologies-tar-archive} is the file name of the redacted technologies tar archive provided.
  1. If you need to require authentication, configure the user and password to connect to your registry using skopeo login (refer to Skopeo login).
  2. Run the following command in the decompressed archive to launch the image upload:
./pushall.sh {registry} where {registry} is the hostname of your Docker registry.

Install technology repository

The repository containing your technologies needs be installed manually in your cluster.

TIP: Refer to the redacted SDK documentation (link removed) for more information about adding technologies.

  1. Copy the path to the `technologies.zip` file (link removed) that contains your technologies.
  2. Run the following `redactedctl` command to install the repository in your cluster:
./bin/redactedctl upload technologies --file {technologies-file} where {technologies-file} is the path to your technologies.zip file.

Install TLS certificate

A TLS certificate is required and needs to be installed in your Kubernetes cluster. Make sure that your TLS certificate is valid for the DNS entry you determined when verifying your prerequisites.

The following instructions will guide you through installing or updating the certificate in your Kubernetes cluster.

Install certificate

Generate an encoded version of your certificate files

  1. Generate a Base-64 encoded version of the certificate:
    • Linux: cat server.pem | base64 -w 0
    • macOS: cat server.pem | base64 | tr -d '\n'
  2. Generate a Base-64 encoded version of the key:
    • Linux: cat server-key.pem | base64 -w 0
    • macOS: cat server-key.pem | base64 | tr -d '\n'

Create & deploy certificate

  1. Create a certificate.yml file with the following content.

The certificate.yml file appears here in the guide.

  1. Deploy your certificate:
kubectl apply -f certificate.yml

Update certificate

If you are updating your certificate after redacted has been installed, you will also need to restart the ingress controllers and verify that the new certificate is now being used.

  1. Restart the ingress controllers to take into account the new certificate.
kubectl delete pod -n redacted-common -l "app.kubernetes.io/component=controller,app.kubernetes.io/instance=redacted-common,app.kubernetes.io/name=ingress-nginx"
  1. Verify that the new certificate is being used by running the following command, then checking the `server certificate` section of the output:
curl -k -v -I "https://{prefix}-{suffix}.{domain}", where {prefix}, {suffix}, and {domain} are the DNS entry components you determined when verifying your prerequisites.

End of sample

© Coley Woyak. All rights reserved.
Original design: Paradigm Shift by HTML5 UP & customized by yours truly.