msp: refresh intro, add image guidance (#8651)

1. Add use cases section
2. Add Loom recording of Merge talk
3. Add intro on building images (incomplete for now)
4. Organize such that we have an explicit "Getting started" section

content/departments/engineering/teams/core-services/managed-services/platform.md

@@ -5,9 +5,14 @@ MSP takes a service specification and generates Terraform manifests and adjacent
 
 By adopting MSP for your managed service, it will benefit from [an expanding set of features and integrations](#features), alignment with infrastructure and security best practices at Sourcegraph, and support from the [Core Services team](../index.md).
 
-All assets are managed in [sourcegraph/managed-services](https://github.com/sourcegraph/managed-services), and the tooling is being developed in [sourcegraph/sourcegraph/dev/sg/msp](https://github.com/sourcegraph/sourcegraph/tree/main/dev/sg/msp).
+## Use cases
 
-> [!WARNING] This project and page is a work in progress. For some context, see [go/rfc-msp](http://go/rfc-msp).
+Any "managed service" - internal or customer-facing, for testing or for production - can be operated on Managed Services Platform!
+Today, MSP operates both internal and external services from many teams across Sourcegraph - see the [Managed Services infrastructure page](../../../managed-services/index.md) for a generated listing.
+
+For an intro on what "managed services" are and how MSP can help you, check out this Loom introduction: [Creating and Operating Managed Services at Sourcegraph (Merge 2024)](https://www.loom.com/share/be0a6de474de453b80c6a4e7beaed9c2?sid=94784206-e62d-48a6-9ea4-e342ebfcaab0), and refer to [features](#features) to see what MSP can offer.
+
+**✨ Ready to spin up a new service? Check out our [Getting started](#getting-started) guide!**
 
 ## Features
 
@@ -19,8 +24,8 @@ MSP supports single-container:
 From a simple service configuration YAML ([examples](https://github.com/sourcegraph/managed-services/tree/main/services)) and the `sg msp` toolchain for managing configuration, we currently support:
 
 - Generating infrastructure-as-code, deployed via Terraform Cloud
-- [Service initialization and runtime boilerplate](#building-a-new-service) via [sourcegraph/lib/managedservicesplatform](https://github.com/sourcegraph/sourcegraph/tree/main/lib/managedservicesplatform), which includes:
-  - initialization of OpenTelemetry tracing and metrics, logging, and error reporting
+- [Service initialization and runtime boilerplate](#service-code) via [sourcegraph/lib/managedservicesplatform](https://github.com/sourcegraph/sourcegraph/tree/main/lib/managedservicesplatform), which includes:
+  - initialization of OpenTelemetry tracing and metrics, logging, and error reporting (Sentry)
   - integration guidance for provisioned data backends like Redis and PostgreSQL
 - Provisioning of data backends, configured with secure, highly available defaults and regular backups out of the box where applicable:
   - [Redis](https://cloud.google.com/memorystore/docs/redis/memorystore-for-redis-overview) for ephemereal data and synchronization between instances of a service.
@@ -39,12 +44,22 @@ From a simple service configuration YAML ([examples](https://github.com/sourcegr
 
 See [our GitHub roadmap](https://github.com/orgs/sourcegraph/projects/375/views/1) and [2023 Q3 Managed Services Platform (MSP) proof-of-concept update](https://docs.google.com/document/d/1DSqKqCgXW2m0TCVBmDSasY2Hxb9cp9Uv_NgF4MEfAto/edit) for more details on things we will be adding to MSP.
 
-## Building a new service
+## Operating services
+
+All infrastructure manifests are managed in [sourcegraph/managed-services](https://github.com/sourcegraph/managed-services), and the tooling is being developed in [sourcegraph/sourcegraph/dev/sg/msp](https://github.com/sourcegraph/sourcegraph/tree/main/dev/sg/msp).
+
+- **Guidance for service operators** is available in the [Managed Services infrastructure](../../../managed-services/index.md) pages.
+- **Guidance for broad MSP incidents** is available in [Managed Services incident response](./incidents.md) - this is generally intended for Core Services.
+
+## Getting started
+
+Before [deploying a service](#creating-and-configuring-infrastructure), you will need to [write some code](#service-code) and [build the service for distribution in MSP](#service-images).
+
+### Service code
 
-Before deploying a service, you will need to build it!
 The Core Services team recommends building your service in Go to leverage the service initialization and runtime boilerplate provided by the standalone [github.com/sourcegraph/sourcegraph/lib/managedservicesplatform](https://github.com/sourcegraph/sourcegraph/tree/main/lib/managedservicesplatform) module.
 
-The `runtime.Start` function outlines the expected "contract" the MSP runtime expects services to fulfill:
+The `runtime.Start` function outlines the expected "contract" the MSP runtime expects services to fulfill, and ensures your service is compatible with MSP infrastructure:
 
 ```go
 import (
@@ -59,15 +74,24 @@ func main() {
 }
 ```
 
-In your implementation of `runtime.Service`, the primary entrypoint `Initialize` provides a `runtime.Contract` that is pre-configured with MSP defaults and offers helpers to connecting to MSP-provisioned resources. For example, to serve your service, you must use `(runtime.Contract).Port`, and to get a securely authenticated PostgreSQL connection, you can use `(runtime.Contract).PostgreSQL.OpenDatabase(...)`.
+In your implementation of `runtime.Service`, the primary entrypoint `Initialize` provides a `runtime.Contract` that is pre-configured with MSP defaults and offers helpers to integrating with MSP-provisioned resources. For example:
+
+- to serve your service, you must use `(runtime.Contract).Port`
+- to get a securely authenticated PostgreSQL connection, you can use `(runtime.Contract).PostgreSQL.OpenDatabase(...)`
+- Sentry error reporting integration for error-level logs is automatically configured when using the provided logger instance
 
 A full example service is available in [`cmd/msp-example`](https://github.com/sourcegraph/sourcegraph/tree/main/cmd/msp-example) that makes use of most MSP functionality.
 
-## Creating and configuring infrastructure for services
+### Service images
 
-Refer to the [sourcegraph/managed-services README](https://github.com/sourcegraph/managed-services/blob/main/README.md) for all documentation for creating configuring MSP deployments and using `sg msp`.
+MSP expects Docker images built for the `linux/amd64` platform.
+If you are using a recent Macbook, this means that images built locally do not work out of the box - you must build images with [the `--platform=linux/amd64` flag](https://docs.docker.com/build/building/multi-platform/#building-multi-platform-images), or build your images and publish in CI.
 
-## Operating services
+When publishing images for MSP to consume, you can use the public Docker registry, or an [Artifact Registry](https://cloud.google.com/artifact-registry) repository within the Sourcegraph GCP organization.
+When using a Docker registry within GCP, MSP will automatically provision the prerequisite permissions for MSP to access your images.
 
-- **Guidance for service operators** is available in the [Managed Services infrastructure](../../../managed-services/index.md) pages.
-- **Guidance for broad MSP incidents** is available in [Managed Services incident response](./incidents.md) - this is generally intended for Core Services.
+> [!WARNING] More guidance coming soon!
+
+### Creating and configuring infrastructure
+
+Refer to the [sourcegraph/managed-services README](https://github.com/sourcegraph/managed-services/blob/main/README.md) for all documentation for creating configuring MSP deployments and getting started with `sg msp`.