Creating a managed instance

Creating a new managed instance involves following the steps below. For basic operations like accessing an instance for these steps, see managed instances operations.

1. CE creates an issue with the managed instance template in the sourcegraph/customer repository.
2. Create a new GCP project for the instance by adding it to the managed_projects tfvar in the infrastructure repo’s gcp/projects/terraform.tfvars
   • It will look something like sourcegraph-managed-$COMPANY = { ... } - refer to the existing variables for more details. If you customize the sourcegraph-managed prefix, make sure to update the PROJECT_PREFIX variable in the below instructions.
   • Ensure when you run terraform apply that you commit and push the terraform.tfstate file to github
3. Clone and cd deploy-sourcegraph-managed/
4. Set variables:

• export VERSION=vMAJOR.MINOR.PATH
• export COMPANY=$COMPANY
• export PROJECT_PREFIX=sourcegraph-managed (should match GCP project prefix)
• export PROJECT_ID=$PROJECT_PREFIX-$COMPANY
• export TF_VAR_opsgenie_webhook=<OpsGenie Webhook value>
  • This can be found in the Managed Instances vault
• export TF_VAR_cf_origin_cert_base64=$(gcloud secrets versions access latest --project=sourcegraph-dev --secret="SOURCEGRAPH_WILDCARD_CERT" | base64)
• export TF_VAR_cf_origin_private_key_base64=$(gcloud secrets versions access latest --project=sourcegraph-dev --secret="SOURCEGRAPH_WILDCARD_KEY" | base64)

1. Check out a new branch: git checkout -b $COMPANY/create-instance
2. ./util/create-managed-instance.sh $COMPANY/ and commit the result. Make sure that the version exists in deploy-sourcegraph-docker.
3. Open and edit deploy-sourcegraph-managed/$COMPANY/gcp-tfstate/gcp-tfstate.tf according to the TODO comments within, commit the result.
4. Ensure you are using the version of Terraform indicated in .tool-versions using tfenv
5. In gcp-tfstate run terraform init && terraform apply && git add . && git commit -m 'initialize GCP tfstate bucket'
6. Open and edit infrastructure.tf according to the TODO comments within and commit the result.
7. Open and edit terraform.tfvars according to the TODO comments within and commit the result.
8. Open and edit deploy-sourcegraph-managed/$COMPANY/red/docker-compose/docker-compose.yaml, increase gitserver-0’s cpus: 8 and GOMAXPROCS=8 if the instance size is larger than “n1-standard-8”.
9. In deploy-sourcegraph-managed/$COMPANY run ./enable-apis.sh
10. In deploy-sourcegraph-managed/$COMPANY run terraform init && terraform plan && terraform apply
11. Access the instance over SSH and confirm all containers are healthy (instructions). You may find docker ps reports no containers, that indicates it is still installing Docker, etc. To watch this progress see debugging startup scripts, it usually takes <10m.
12. In the infrastructure repository, create a DNS entry that points $COMPANY.sourcegraph.com to the default-global-address IP (see “Finding the external load balancer IP”) and follow the process there to asdf exec terraform apply it. If the instance is Public, set proxied to true. If it’s Private, set it to false.
13. Confirm all containers come up healthy (docker ps should report them as such)
14. Create a PR for review.
15. Create admin credentials in 1password:
    • Open the 1password Managed instances vault (ask @stephen, @bill, or @beyang to grant you access)
    • Add > Login > enter $COMPANY sourcegraph-admin as the title
      • User: managed+$COMPANY@sourcegraph.com
      • Password: Change length to 40 and turn on symbols and digits > Save
16. Access the Sourcegraph web UI (instructions for port-forwarding)
17. Set up the initial admin account (for use by the Sourcegraph team only)
    • Email: managed+$COMPANY@sourcegraph.com (note + sign not -)
    • Username: sourcegraph-admin
    • Password: Use the password previously created and stored in 1password.
18. Create a token for the account under /users/sourcegraph-admin/settings/tokens called managed-instances and add it as “token” under the 1password entry for the admin account.
19. Navigate to Grafana and confirm the instance looks healthy.
20. Configure externalURL in the site configuration, and use SSH to restart the server (sudo su, shutdown -r) wait for it to come back up and access it again.
21. In the global user settings (not site config), set "alerts.showPatchUpdates": false
22. In the GCP web UI under Network services > Load balancers > select the load balancer > watch the SSL certificate status. It may take some time for it to become active (~1h41m) / for Google to see the DNS change from Cloudflare. Confirm it is active by following “Access through the GCP load balancer as a user would”.
23. In the site configuration, configure alerting to go to our #alerts-managed-instances Slack channel, for example (replace $COMPANY with the actual company name, and $WEBHOOK_URL with the actual webhook URL from 1password Managed instances > #alerts-managed-instances Slack webhook URL):

    	"observability.alerts": [
    		{
    			"level": "critical",
    			"notifier": {
    				"type": "slack",
    				"username": "$COMPANY",
    				"url": "$WEBHOOK_URL"
    			}
    		},
    	],
    

24. In the site configuration, configure password reset emails to expire after 24 hours (instead of the default 4 hours). This allows more time for the customer to set up their initial account and gain access to the instance.

    "auth.passwordResetLinkExpiry": 86400, // 24 hours
    

25. Add an entry for the customer by adding their Accounts link to the checklist in the managed instances upgrade issue template.