Skip to content

Latest commit

 

History

History

01-setup

README.md

01 - Setup

⏱ Estimated time: 45 minutes

What you'll build

Architecture diagram of the supergraph

Part A: Gather accounts and credentials

Clone this repo

git clone https://github.com/apollosolutions/build-a-supergraph.git
cd build-a-supergraph
git pull

Install dependencies

Gather accounts

Gather credentials

Export all necessary variables

Make a copy of .env.sample called .env to keep track of these values. You can always run source .env to reload all environment variables in a new terminal session.

cd 01-setup/
cp .env.sample .env

Edit the new .env file:

export PROJECT_ID="<your google cloud project id>"
export APOLLO_KEY="<your apollo personal api key>"
export GITHUB_ORG="<your github org>"
export TF_VAR_github_token="<your github personal access token>"

Run this script to create your graph and get environment variables for GraphOS:

cd 01-setup
source .env
./create_graph.sh

The script adds a couple more environment variables to .env, so reload your environment now:

source .env

Run setup commands

gcloud components update
gcloud components install gke-gcloud-auth-plugin
gcloud auth application-default login

gcloud config set project ${PROJECT_ID}
gcloud services enable \
  container.googleapis.com \
  secretmanager.googleapis.com \
  cloudasset.googleapis.com \
  storage.googleapis.com
gh auth login
Optional: how do I specify a different name for clusters and repos? (The default is "apollo-supergraph-k8s".)

Before running create_graph.sh, setup_clusters.sh, or terraform apply export the prefix as as environment variables:

export CLUSTER_PREFIX=my-custom-prefix
export TF_VAR_demo_name=$CLUSTER_PREFIX

Part B: Provision resources

Have you run this tutorial before?

You may need to clean up your Github packages before creating new repos of the same name. Visit https://github.com/<your github username>?tab=packages and delete the packages created by the previous versions of the repos.

Create Kubernetes clusters, basic infrastructure, and Github repositories

Note: The following commands will create resources on your GCP account, and begin to accrue a cost. The example infrastructure defaults to a lower-cost environment (small node count and instance size), however it will not be covered by GCP's free tier.

cd 01-setup
terraform init # takes about 2 minutes
terraform apply # will print plan then prompt for confirmation
# takes about 10-15 minutes

Expected output:

kubernetes_cluster_names = {
  "dev" = "apollo-supergraph-k8s-dev"
  "prod" = "apollo-supergraph-k8s-prod"
}
repo_infra = "https://github.com/you/apollo-supergraph-k8s-infra"
repo_subgraph_a = "https://github.com/you/apollo-supergraph-k8s-subgraph-a"
repo_subgraph_b = "https://github.com/you/apollo-supergraph-k8s-subgraph-b"
What does this do?

Terraform provisions:

  • Two Kubernetes clusters (dev and prod)
  • Three Github repos (subgraph-a, subgraph-b, infra)
  • Github action secrets for GCP and Apollo credentials

The subgraph repos are configured to build and deploy to the dev cluster once they're provisioned. (The deploy will fail the first time. See "Note about "initial commit" errors" below.)

Run cluster setup script

After creating the necessary clusters, you will need to run the included cluster setup script:

cd 01-setup
./setup_clusters.sh # about 2 minutes
What does this do?

For both dev and prod clusters:

  • Configures your local kubectl so you can inspect your clusters
  • Configures namespace, service account, and role bindings for Open Telemetry and Google Traces.

After this completes, you're ready to deploy your subgraphs!

Part C: Deploy applications

Deploy subgraphs to dev

gh workflow run "Merge to Main" --repo $GITHUB_ORG/apollo-supergraph-k8s-subgraph-a
gh workflow run "Merge to Main" --repo $GITHUB_ORG/apollo-supergraph-k8s-subgraph-b
# this deploys a dependency for prod, see note below
gh workflow run "Deploy Open Telemetry Collector" --repo $GITHUB_ORG/apollo-supergraph-k8s-infra
Note about "initial commit" errors

When terraform creates the repositories, they immediately kick off initial workflow runs. But the secrets needed are available at that point. The "initial commit" runs will fail, but we're just re-running them with the commands above.

You can try out a subgraph using port forwarding:

kubectx apollo-supergraph-k8s-dev
kubectl port-forward service/graphql -n subgraph-a 4000:4000

Then visit http://localhost:4000/.

Deploy subgraphs to prod

Commits to the main branch of the subgraph repos are automatically built and deployed to the dev cluster. To deploy to prod, run the deploy actions:

gh workflow run "Manual Deploy" --repo $GITHUB_ORG/apollo-supergraph-k8s-subgraph-a \
  -f version=main \
  -f environment=prod \
  -f dry-run=false \
  -f debug=false

gh workflow run "Manual Deploy" --repo $GITHUB_ORG/apollo-supergraph-k8s-subgraph-b \
  -f version=main \
  -f environment=prod \
  -f dry-run=false \
  -f debug=false
kubectx apollo-supergraph-k8s-prod
kubectl port-forward service/graphql -n subgraph-a 4000:4000

Then visit http://localhost:4000/.

Onward!

Step 2: Managed Federation