diff --git a/content/departments/engineering/teams/core-services/managed-services/platform.md b/content/departments/engineering/teams/core-services/managed-services/platform.md index 44a930304639..66566b2b1a1b 100644 --- a/content/departments/engineering/teams/core-services/managed-services/platform.md +++ b/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`.