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. Create a 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
   • 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_ID=sourcegraph-managed-$COMPANY
   • export TF_VAR_opsgenie_webhook=<OpsGenie Webhook value>
     • This can be found in the Managed Instances vault
5. Check out a new branch: git checkout -b $COMPANY/create-instance
6. ./util/create-managed-instance.sh $COMPANY/ and commit the result. Make sure that the version exists in deploy-sourcegraph-docker.
7. Open and edit deploy-sourcegraph-managed/$COMPANY/gcp-tfstate/gcp-tfstate.tf according to the TODO comments within, commit the result.
8. Ensure you are using the version of Terraform indicated in .tool-versions using tfenv
9. In gcp-tfstate run terraform init && terraform apply && git add . && git commit -m 'initialize GCP tfstate bucket'
10. Open and edit infrastructure.tf according to the TODO comments within and commit the result.
11. Open and edit terraform.tfvars according to the TODO comments within and commit the result.
12. In deploy-sourcegraph-managed/$COMPANY run ./enable-apis.sh
13. In deploy-sourcegraph-managed/$COMPANY run terraform init && terraform plan && terraform apply
14. 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.
15. 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.
16. Confirm all containers come up healthy (docker ps should report them as such)
17. Create a PR for review.
18. 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
19. Access the Sourcegraph web UI (instructions for port-forwarding)
20. 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.
21. 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.
22. Navigate to Grafana and confirm the instance looks healthy.
23. 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.
24. In the global user settings (not site config), set "alerts.showPatchUpdates": false
25. 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”.
26. 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"
    			}
    		},
    	],
    

27. Add an entry for the customer by adding their HubSpot link to the checklist in the managed instances upgrade issue template.
28. Contact the CE who requested the instance and ask that they generate / provide the relevant license key for the customer’s instance, then set it in the site config. If the requesting CE is unavailable or this was an internal instance, ask #ce for assistance.