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
  3. Clone and cd deploy-sourcegraph-managed/
  4. Set variables:
    • export VERSION=vMAJOR.MINOR.PATH
    • export COMPANY=$COMPANY
    • export PROJECT_ID=sourcegraph-managed-$COMPANY
  5. Check out a new branch: git checkout $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: [email protected]
      • 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: [email protected] (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 #ce and ask that they generate / provide the relevant license key for the customer’s instance, then set it in the site config.

Giving the customer access

To provide the customer access to the instance:

  1. Work with #ce to ask the customer:
    1. If their instance should be protected by SSO only, or SSO + IP-restricted access. If the latter, what IP addresses / CIDR ranges should be allowed (e.g. the source IPs of their corporate VPN, usually their infrastructure or IT teams can provide this).
    2. Who should be the recipient of the initial site admin account creation link? This will let them configure the admin password, which they will need to store somewhere securely, and is used for them to set up SSO as well as for them to get access if at any point SSO is not working. They can create more password or SSO-based admin accounts later as desired.
  2. Create and apply the Terraform change that grants their IP/CIDR ranges access to the instance, or makes it public/SSO-only, by following the operations guide.
  3. Prepare the initial admin account for the customer:
    1. Go to /site-admin/users and hit “Create user”, and fill in the appropriate values.
    2. Copy the generated link and send it to the customer. Managed instances usually won’t have email set up, so a link will not be sent automatically.
    3. Go to /site-admin/users and promote the created account to site admin.

Configuring SSO and repositories

Distribution usually hands off to CE at this point, they will schedule a call with the customer (including a distribution member, if needed) to walk the site admin on the customer’s side through performing initial setup of the product including adding repos, configuring SSO, and inviting users.