GCP Deployment

This document describes the deployment of the required Atolio services into Google Cloud Platform (GCP). This document is intended to be followed in linear order, skipping any steps not relevant to the particular deployment.

Architecture

arch-gcp

Deployment Prerequisites

Before getting started, Atolio needs to have done the following on your behalf:

  1. Granted your GCP project access to the Client Container Registry repos (for pulling Atolio container images)
  2. Add your Deployment Engineer as a collaborator to the Atolio GitHub repository (lumen-infra), which contains:
    • Deployment documentation
    • Terraform for the Atolio stack infrastructure
    • Configuration files for Atolio services
    • Maintenance scripts
  3. Ensure your GCP project has sufficient quota for the required resources, particularly Compute Engine API and Google Kubernetes Engine API.

The following deployment prerequisites will help streamline your deployment process.

Determine GCP project

We recommend you create a new GCP project to host Atolio, as this will help keep your Atolio deployment and other resources separate from your production environment. When the project is available, share the GCP project ID and number with your Atolio support team.

Determine Deployment Model

We offer both Atolio managed and customer managed deployment models for you to choose from. Please review the comparison and requirements for each approach on our Deployment Model Overview page and inform your Atolio support team which method you’d like to use for your deployment.

Determine Atolio DNS name

Before the deployment call, you may want to decide on your desired Atolio web address. A GCP Cloud DNS zone will be created in the GCP project used for hosting the Atolio stack (e.g. search.example.com.): this will be the DNS name (without the trailing dot) for the Atolio web application (e.g. https://search.example.com).

This Cloud DNS zone allows the deployment control plane (i.e. the External DNS controller) to add records to link host names (e.g. search.example.com, feed.search.example.comand relay.search.example.com) to the Ingress controller used for the deployment.

For the remainder of this document, we will use https://search.example.com in the examples, but it is expected for you to replace with your own DNS name.

Setup authentication

Atolio supports single sign-on (SSO) authentication through Okta, Microsoft Entra ID, and Google using the OpenID Connect (OIDC) protocol.

Refer to Configuring Authentication for more details on the steps to complete in your desired SSO provider in order to obtain the necessary OIDC configuration values.

Setup local environment

Finally, if an engineer from your team will be performing the deployment, ensure they have the following utilities installed:

Provide Deployment Engineer with Configuration

At this point if you’re proceeding with an Atolio managed deployment you’ll need to provide the information from these prerequisite steps to your Atolio deployment support team. Otherwise please ensure the information is provided to the engineer from your organization who will be performing the deployment with Atolio’s support.

To recap, provide these details:

If you’re opting to have Atolio manage the deployment you can disregard the remainder of this documentation as these steps will be performed by your Atolio deployment engineer. Otherwise be sure to share this documentation with the engineer from your organization that will be performing the deployment so they can familarize theirself with the steps required.

Create Cloud Infrastructure

The Terraform configuration requires an external (Google Cloud Storage) bucket to store state. A script is available to automate the whole process (including running Terraform). Before running the script, create a config.hcl file based on the provided config.hcl.template:

cd deploy/terraform/gcp
cp ./config.hcl.template config.hcl

Update the copied file with appropriate values. At a minimum, it should specify the zone you’re deploying to:

// Core Configuration
zone = "us-central1-f"

Atolio Domain Name

Update the copied file with subdomain you will use for your Atolio deployment values:

# Domain name for Atolio stack (same as hosted zone name without trailing ".")
lumen_domain_name = "search.example.com"

Application Helm Value Options

Next copy the Helm template and update the values as directed.

cp ./templates/values-lumen-admin.yaml values-lumen.yaml
cp ./templates/values-vespa-admin.yaml values-vespa.yaml

# Default values for lumen.
# This is a YAML-formatted file.
# Declare variables to be passed into your templates (provided by admin user).

# JWT secret key for API call (signature) verification (at least 256 bits / 32 chars)
# Can be generated by running `openssl rand -base64 32` in your terminal
jwtSecretKey: "add-your-jwt-secret-key-here"

# Secret salts for generating Vespa document IDs
# Can be generated by running `openssl rand -base64 32` in your terminal
secretSalts: "add-your-secret-salts-here"

# See also scripts/config-oidc.sh helper script to obtain some of the values below
oidc:
  provider: "add-your-provider-here"
  endpoint: "add-your-endpoint-here"
  clientId: "add-your-id-here"
  clientSecret: "add-your-secret-here"

# If running behind a reverse proxy, this should be set to the URL the end user will
# use to access the product.
reverseProxyUrl: ""

# The ACME Cluster Issuer for LetsEncrypt requires an email address to be provided
# for certificate notifications. This is required for LetsEncrypt certificates to work properly.
# Common examples would be an admin or technical support email address for your organization. ex: "admin@example.com" or "engineering@example.com".
letsencrypt:
  email: "letsencrypt@example.com"

For the jwtSecretKey and secretSalts values any 256 bit (32 character) string can be used. These values are used to sign JWT tokens used by the web application and atolioctl tool and salt document IDs in Atolio’s database. They should be well guarded secrets that are unique to the deployment.

If your users will be accessing the web interface via a reverse proxy (e.g. such as StrongDM), then be sure to set the reverseProxyUrl field to reflect the URL they will actually enter into their browser to access Atolio, which will be different to the hostname defined in lumen_domain_name. Leave this field empty if not using a reverse proxy.

The ACME Cluster Issuer for LetsEncrypt requires an email address to be provided for certificate notifications. If the default @example.com email address is used, then the Cluster Issuer will fail to register for certificate management so be sure to provide a valid email address.

Deployment with create-infra.sh script

Once you have all variables configured, you can create the infrastructure and deploy the GKE cluster. From the deploy/terraform/gcp directory:

./scripts/create-infra.sh --name=acmecorp

This will create the infrastructure in the us-central1 GCP region. If you want to deploy in another region parameter (e.g. us-west2) an additional parameter can be provided:

./scripts/create-infra.sh --name=acmecorp --region=us-west2

The --name argument is used to generate a deployment name for tagging resources and naming the GCP resources. So make sure it is unique across all deployments. (i.e. using a globally unique deployment name). Typically this is set to your company name with an optional suffix if specifying environment (e.g. acmecorp or acmecorp-qa).

The script automates the following steps (parameterized based on the provided deployment name):

  1. Create a Google Cloud Storage bucket to store Terraform state
  2. Create a terraform.tfvars file for Terraform based on the config.hcl file
  3. Run terraform init
  4. Run terraform apply (using input variables in generated terraform.tfvars)

Post-deployment steps

With the infrastructure created, you’ll want to update your local kubeconfig with a context for the Atolio cluster (this is also output via Terraform as update_kubeconfig_command):

gcloud container clusters get-credentials lumen-{deployment-name} --region us-central1 --project {your-gcp-project-id}

Delegate responsibility for Atolio subdomain

The parent domain (e.g. example.com) needs to delegate traffic to the new Atolio subdomain (search.example.com). This is achieved by adding an NS record to the parent domain with the 4 name servers copied from the new subdomain.

These nameservers can be retrieved post-creation with terraform output:

terraform output --json name_servers | jq -r '.[]'

Deployment Verification

At this point you should be able to interact with the Kubernetes cluster and see Atolio pods deployed, e.g.

kubectl get po -n atolio-svc

Note, Atolio specific services run on the following namespaces:

  • atolio-svc (Application Services)
  • atolio-db (Database)
  • atolio-ctl (Control Plane)

When you have validated that the infrastructure is available, the next step is to configure sources.