diff --git a/src/current/_data/redirects.yml b/src/current/_data/redirects.yml index 28c4f96b318..9b664212ea2 100644 --- a/src/current/_data/redirects.yml +++ b/src/current/_data/redirects.yml @@ -1158,3 +1158,6 @@ - destination: update.md sources: ['update-data.md'] versions: ['v26.1', 'v26.2'] + +- destination: cockroachcloud/byoc-azure-deployment.md + sources: ['cockroachcloud/byoc-deployment.md'] diff --git a/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md new file mode 100644 index 00000000000..6f5923dac63 --- /dev/null +++ b/src/current/_includes/cockroachcloud/byoc/byoc-common-prerequisites.md @@ -0,0 +1,9 @@ +- Review the [shared responsibility model for BYOC]({% link cockroachcloud/byoc-overview.md %}#shared-responsibility-model-for-byoc). Make sure you understand and acknowledge the responsibilities you hold for management of your cloud infrastucture and the necessary permissions you must grant to Cockroach Labs. + +- [Create a CockroachDB {{ site.data.products.cloud }} organization]({% link cockroachcloud/create-an-account.md %}) if you do not already have one. + +- The BYOC deployment option is not available by default and must be requested. Reach out to your account team to express interest in BYOC. + +- Once your cloud account is prepared for a CockroachDB BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. + +- Review cloud service regions supported by [CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }}]({% link cockroachcloud/regions.md %}?filters=advanced). \ No newline at end of file diff --git a/src/current/_includes/feature-phases/preview.md b/src/current/_includes/feature-phases/preview.md index 5506a046ba7..8deaa37bcd6 100644 --- a/src/current/_includes/feature-phases/preview.md +++ b/src/current/_includes/feature-phases/preview.md @@ -5,4 +5,4 @@ {% assign link_version = page.version.version %} {% endif %} -**This feature is in [preview]({{base_url}}{{link_version}}/cockroachdb-feature-availability.html)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com/hc/en-us). \ No newline at end of file +**This feature is in [preview]({{base_url}}{{link_version}}/cockroachdb-feature-availability.html)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com). diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index 3114b07c714..21e835a4084 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -21,9 +21,32 @@ ] }, { - "title": "BYOC Deployments (Preview)", - "urls": [ - "/cockroachcloud/byoc-deployment.html" + "title": "Bring Your Own Cloud (BYOC)", + "items": [ + { + "title": "BYOC Overview", + "urls": [ + "/cockroachcloud/byoc-overview.html" + ] + }, + { + "title": "Deploy BYOC on AWS", + "urls": [ + "/cockroachcloud/byoc-aws-deployment.html" + ] + }, + { + "title": "Deploy BYOC on Azure", + "urls": [ + "/cockroachcloud/byoc-azure-deployment.html" + ] + }, + { + "title": "Deploy BYOC on GCP", + "urls": [ + "/cockroachcloud/byoc-gcp-deployment.html" + ] + } ] }, { diff --git a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json index 6ae5a968ddd..1c822f96cd0 100644 --- a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json @@ -21,9 +21,32 @@ ] }, { - "title": "BYOC Deployments (Preview)", - "urls": [ - "/cockroachcloud/byoc-deployment.html" + "title": "Bring Your Own Cloud (BYOC)", + "items": [ + { + "title": "BYOC Overview", + "urls": [ + "/cockroachcloud/byoc-overview.html" + ] + }, + { + "title": "Deploy BYOC on AWS", + "urls": [ + "/cockroachcloud/byoc-aws-deployment.html" + ] + }, + { + "title": "Deploy BYOC on Azure", + "urls": [ + "/cockroachcloud/byoc-azure-deployment.html" + ] + }, + { + "title": "Deploy BYOC on GCP", + "urls": [ + "/cockroachcloud/byoc-gcp-deployment.html" + ] + } ] }, { diff --git a/src/current/cockroachcloud/advanced-cluster-management.md b/src/current/cockroachcloud/advanced-cluster-management.md index 998b04e7d58..3bcb0f1530c 100644 --- a/src/current/cockroachcloud/advanced-cluster-management.md +++ b/src/current/cockroachcloud/advanced-cluster-management.md @@ -9,10 +9,6 @@ docs_area: manage This page describes the cluster management and cluster deletion workflows for CockroachDB {{ site.data.products.advanced }}. -{{site.data.alerts.callout_danger}} -If you are managing clusters in a [BYOC deployment]({% link cockroachcloud/byoc-deployment.md %}) you must use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to perform the actions described on this page. -{{site.data.alerts.end}} - ## Planning your cluster Before making any changes to your cluster's nodes or regions, review the [requirements and recommendations]({% link cockroachcloud/plan-your-cluster.md %}) for CockroachDB {{ site.data.products.cloud }} cluster configuration. diff --git a/src/current/cockroachcloud/byoc-aws-deployment.md b/src/current/cockroachcloud/byoc-aws-deployment.md new file mode 100644 index 00000000000..de2d7d54d04 --- /dev/null +++ b/src/current/cockroachcloud/byoc-aws-deployment.md @@ -0,0 +1,274 @@ +--- +title: Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services +summary: Prepare an Amazon Web Services account to host a BYOC deployment of CockroachDB +toc: true +keywords: deployment, byoc +--- + +This page describes how to prepare a cloud service account to host a [BYOC deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Amazon Web Services (AWS). + +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} + +## Prerequisites + +{% include cockroachcloud/byoc/byoc-common-prerequisites.md %} + +- Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. + +## Step 1. Create a new AWS account + +Provision a new AWS account with no existing infrastructure, dedicated to your CockroachDB {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this account, so this step is necessary to isolate these permissions from non-CockroachDB Cloud resources. + +## Step 2. Collect the Cockroach Labs IAM role ARN + +Cockroach Labs uses cross-account resource management to provision and manage resources in your AWS account. This requires two **IAM roles**: + +- An IAM role owned by Cockroach Labs which must be granted permissions to access an IAM role in your AWS account. +- An intermediary IAM role in your AWS account which must be granted permissions to create and manage infrastructure. This IAM role is the target used by Cockroach Labs for cross-account management. + +In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to get the **Amazon Resource Name (ARN)** of the IAM role provisioned by Cockroach Labs for your account. + +Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/organization \ + --header 'Authorization: Bearer {secret_key}' +~~~ + +Record the value of `cockroach_cloud_service_principals.aws.user_arn` in the response: + +~~~ json +{ + "cockroach_cloud_service_principals": { + "aws": { + "user_arn": "arn:aws:iam::{AWS Account ID}:example/arn" + } + } +} +~~~ + +## Step 3. Create intermediary IAM role and apply permissions + +In this step, create the intermediary IAM role in your AWS account, then apply a trust relationship policy and permissions that allow Cockroach Labs to assume the intermediary role as needed. + +Follow these steps to create the intermediate IAM role: + +1. Open the AWS IAM console. +1. Create a new role. You can choose any name for this role. In these instructions the example role is named `CRLBYOCAdmin`. +1. Use the following trust relationship policy for the new role, using the ARN collected in the previous step: + {% include_cached copy-clipboard.html %} + ~~~ json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::{AWS Account ID}:example/arn" + }, + "Action": "sts:AssumeRole" + } + ] + } + ~~~ +1. Apply an IAM policy to the intermediate role granting the following list of permissions: + {% include_cached copy-clipboard.html %} + ~~~ text + // Auto Scaling permissions + "autoscaling:CreateAutoScalingGroup", + "autoscaling:DeleteAutoScalingGroup", + "autoscaling:Describe*", + "autoscaling:Get*", + "autoscaling:SetInstanceProtection", + "autoscaling:TerminateInstanceInAutoScalingGroup", + "autoscaling:UpdateAutoScalingGroup", + + // EC2 permissions + "ec2:AcceptVpcEndpointConnections", + "ec2:AcceptVpcPeeringConnection", + "ec2:AssociateRouteTable", + "ec2:AssociateVpcCidrBlock", + "ec2:AttachInternetGateway", + "ec2:AuthorizeSecurityGroupEgress", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateFlowLogs", + "ec2:CreateInternetGateway", + "ec2:CreateLaunchTemplate", + "ec2:CreateLaunchTemplateVersion", + "ec2:CreateNatGateway", + "ec2:CreateRoute", + "ec2:CreateRouteTable", + "ec2:CreateSecurityGroup", + "ec2:CreateSubnet", + "ec2:CreateTags", + "ec2:CreateVpc", + "ec2:CreateVpcEndpoint", + "ec2:CreateVpcPeeringConnection", + "ec2:DeleteFlowLogs", + "ec2:DeleteInternetGateway", + "ec2:DeleteLaunchTemplate", + "ec2:DeleteLaunchTemplateVersions", + "ec2:DeleteNatGateway", + "ec2:DeleteRoute", + "ec2:DeleteRouteTable", + "ec2:DeleteSecurityGroup", + "ec2:DeleteSubnet", + "ec2:DeleteVpc", + "ec2:DeleteVpcEndpoints", + "ec2:DeleteVpcEndpointServiceConfigurations", + "ec2:DeleteVpcPeeringConnection", + "ec2:Describe*", + "ec2:DetachInternetGateway", + "ec2:DisableEbsEncryptionByDefault", + "ec2:DisassociateRouteTable", + "ec2:DisassociateVpcCidrBlock", + "ec2:EnableEbsEncryptionByDefault", + "ec2:Get*", + "ec2:List*", + "ec2:ModifySubnetAttribute", + "ec2:ModifyVolume", + "ec2:ModifyVpcAttribute", + "ec2:ModifyVpcEndpointServiceConfiguration", + "ec2:ModifyVpcEndpointServicePermissions", + "ec2:RejectVpcEndpointConnections", + "ec2:RevokeSecurityGroupEgress", + "ec2:RevokeSecurityGroupIngress", + "ec2:RunInstances", + "ec2:StartVpcEndpointServicePrivateDnsVerification", + + // EKS permissions + "eks:AssociateAccessPolicy", + "eks:CreateAccessEntry", + "eks:CreateCluster", + "eks:DeleteAccessEntry", + "eks:DeleteCluster", + "eks:Describe*", + "eks:DisassociateAccessPolicy", + "eks:List*", + "eks:UpdateAccessEntry", + "eks:UpdateClusterConfig", + "eks:UpdateClusterVersion", + + // Elastic Load Balancing permissions + "elasticloadbalancing:Describe*", + + // IAM permissions + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:AttachUserPolicy", + "iam:CreateAccessKey", + "iam:CreateAccountAlias", + "iam:CreateInstanceProfile", + "iam:CreateOpenIDConnectProvider", + "iam:CreatePolicy", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:CreateUser", + "iam:DeleteAccessKey", + "iam:DeleteInstanceProfile", + "iam:DeleteLoginProfile", + "iam:DeleteOpenIDConnectProvider", + "iam:DeletePolicy", + "iam:DeletePolicyVersion", + "iam:DeleteRole", + "iam:DeleteRolePolicy", + "iam:DeleteUser", + "iam:DeleteUserPolicy", + "iam:DetachRolePolicy", + "iam:DetachUserPolicy", + "iam:Get*", + "iam:List*", + "iam:PassRole", + "iam:PutRolePolicy", + "iam:PutUserPolicy", + "iam:RemoveRoleFromInstanceProfile", + "iam:TagPolicy", + + // Kafka permissions + "kafka:List*", + + // CloudWatch Logs permissions + "logs:CreateLogGroup", + "logs:DeleteLogGroup", + "logs:Describe*", + "logs:Get*", + "logs:List*", + "logs:PutRetentionPolicy", + "logs:PutSubscriptionFilter", + + // S3 permissions + "s3:CreateBucket", + "s3:DeleteBucketPolicy", + "s3:Describe*", + "s3:Get*", + "s3:List*", + "s3:PutBucketTagging", + "s3:PutEncryptionConfiguration", + "s3:PutLifecycleConfiguration", + + // Service Quotas permissions + "servicequotas:GetServiceQuota", + ~~~ + +## Step 4. (Optional) Enable additional regions + +If you plan to use non-default AWS regions, you must manually enable them in the AWS Management Console. You must also activate [global STS tokens](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) for these regions to work with CockroachDB. + +You may also need to adjust quotas for vCPU and EBS disk storage for the regions in which you plan to create your cluster. + +## Step 5. Create the CockroachDB {{ site.data.products.cloud }} cluster + +In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). + +### Create a cluster with the {{ site.data.products.cloud }} Console + +Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: + +1. Open the {{ site.data.products.cloud }} Console and select the organization that has been enabled for BYOC. +1. Click **Create cluster**. +1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. +1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select AWS. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the ARN associated with the intermediate IAM role that you created, *not* the ARN of the Cockroach Labs IAM role. +1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. + +### Create a cluster with the {{ site.data.products.cloud }} API + +Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). + +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east-2` region, specifying the ARN associated with your intermediate IAM role: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ + --url https://cockroachlabs.cloud/api/v1/clusters \ + --header 'Authorization: Bearer {secret_key}' \ + --json '{ + "name": "byoc-aws-cluster-1", + "provider": "AWS", + "spec": { + "dedicated": { + "hardware": { + "machine_spec": {"num_virtual_cpus": 4}, + "storage_gib": 16 + }, + "region_nodes": {"us-east-2": 3} + }, + "plan": "ADVANCED", + "customer_cloud_account": { + "aws": { + "arn": "arn:aws:iam::{AWS Account ID}:example/arn" + } + } + } + }' +~~~ + +## Next steps + +- [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) +- [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/byoc-deployment.md b/src/current/cockroachcloud/byoc-azure-deployment.md similarity index 70% rename from src/current/cockroachcloud/byoc-deployment.md rename to src/current/cockroachcloud/byoc-azure-deployment.md index b5843056e16..ade8702ba16 100644 --- a/src/current/cockroachcloud/byoc-deployment.md +++ b/src/current/cockroachcloud/byoc-azure-deployment.md @@ -1,47 +1,25 @@ --- -title: Prepare a CockroachDB Cloud BYOC Deployment -summary: Prepare a cloud service account to self-host a CockroachDB Cloud deployment with the BYOC model +title: Prepare a CockroachDB Cloud BYOC Deployment in Azure +summary: Prepare a Microsoft Azure account to host a BYOC deployment of CockroachDB toc: true keywords: deployment, byoc --- -CockroachDB {{ site.data.products.cloud }} supports a "bring your own cloud" (BYOC) deployment model, where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. +This page describes how to prepare a cloud service account to host a [BYOC deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. {{site.data.alerts.callout_info}} -The BYOC {{ site.data.products.cloud }} deployment option is currently in [Preview]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %}). BYOC deployments are only supported in Microsoft Azure. +{% include feature-phases/preview.md %} {{site.data.alerts.end}} -This page describes how to prepare a cloud service account to host a BYOC deployment of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Microsoft Azure. - -## Shared responsibility model for BYOC - -In any CockroachDB {{ site.data.products.cloud }} deployment, responsibility for a successful and healthy deployment is [split between you and Cockroach Labs]({% link cockroachcloud/production-checklist.md %}). In a BYOC deployment, all of the [CockroachDB {{ site.data.products.cloud }} infrastructure]({% link cockroachcloud/plan-your-cluster-advanced.md %}#advanced-cluster-architecture) except the control plane lives in an account under your control, which means that you incur additional responsibilities under the shared model. - -The following table describes the split of responsibilities between you and Cockroach Labs in the shared responsibility model for BYOC: - -Area | Cockroach Labs responsibility | Customer responsibility -:----------:|:-----------------------------:|:----------------------: -Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible -Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters -Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable -Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs -Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements -Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available and appropriate IAM permissions are maintained at all times -Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts - ## Prerequisites -- [Create a CockroachDB {{ site.data.products.cloud }} organization]({% link cockroachcloud/create-an-account.md %}) if you do not already have one. - -- The BYOC deployment option is not available by default and must be requested. Reach out to your account team to express interest in BYOC. +{% include cockroachcloud/byoc/byoc-common-prerequisites.md %} -- Cluster creation and management for BYOC deployments is handled using the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). Create a service account and [API key]({% link cockroachcloud/managing-access.md %}#api-access) if you do not have one. - -- Review the [Plan a CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation to plan your cluster sizing and resource allocation. +- (Optional) Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. ## Step 1. Create a new Azure subscription -Provision a new Azure subscription with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this subscription, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This subscription can be reused for multiple CockroachDB clusters. +Provision a new **Azure subscription** with no existing infrastructure, dedicated to your Cockroach {{ site.data.products.cloud }} deployment. The account configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this subscription, so this step is necessary to isolate these permissions from non-Cockroach Cloud resources. This subscription can be reused for multiple CockroachDB clusters. {{ site.data.alerts.callout_danger }} @@ -95,7 +73,7 @@ This reader application also requires admin consent to deploy the reader Service {% include_cached copy-clipboard.html %} ~~~ text - https://login.microsoftonline.com//adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 + https://login.microsoftonline.com/{customer-tenant-id}/adminconsent?client_id=7f6538cb-f687-4411-9bbe-2f96bfbce028 ~~~ 3. Review the requested permissions and click **Accept**. 4. Once the CockroachDB Cloud BYOC Reader App Registration has been granted admin consent in the tenant, grant the following set of roles to the reader Service Principal: @@ -232,7 +210,7 @@ Follow these steps to enable secure, scoped access for Cockroach Labs to your su ~~~ shell az deployment sub create \ --name cockroach-byoc-lighthouse \ - --location \ + --location {region} \ --template-file byoc-lighthouse.json ~~~ @@ -248,7 +226,22 @@ Register the following [resource providers](https://learn.microsoft.com/azure/az ## Step 6. Create the CockroachDB {{ site.data.products.cloud }} cluster -In BYOC deployments, CockroachDB clusters are deployed with the {{ site.data.products.cloud }} API and must use the {{ site.data.products.advanced }} plan. Follow the API documentation to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). +In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). + +### Create a cluster with the {{ site.data.products.cloud }} Console + +Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: + +1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. +1. Click **Create cluster**. +1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. +1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Azure. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the tenant ID and subscription ID associated with your Azure subscription. +1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. + +### Create a cluster with the {{ site.data.products.cloud }} API + +Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `centralus` region, specifying the `subscription-id` and `customer-tenant-id` associated with your Azure subscription: @@ -287,4 +280,4 @@ curl --request POST \ - [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) - [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) -- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) \ No newline at end of file +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/byoc-gcp-deployment.md b/src/current/cockroachcloud/byoc-gcp-deployment.md new file mode 100644 index 00000000000..393f15dce32 --- /dev/null +++ b/src/current/cockroachcloud/byoc-gcp-deployment.md @@ -0,0 +1,144 @@ +--- +title: Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform +summary: Prepare a Google Cloud Platform account to host a BYOC deployment of CockroachDB +toc: true +keywords: deployment, byoc +--- + +This page describes how to prepare a cloud service account to host a [BYOC deployment]({% link cockroachcloud/byoc-overview.md %}) of CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} in Google Cloud Platform (GCP). + +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} + +## Prerequisites + +{% include cockroachcloud/byoc/byoc-common-prerequisites.md %} + +- Create an [API service account]({% link cockroachcloud/managing-access.md %}#create-api-keys) to use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) with your {{ site.data.products.cloud }} organization. + +## Step 1. Create a new GCP project + +Provision a fresh **GCP project** with no existing infrastructure, dedicated to your CockroachDB {{ site.data.products.cloud }} deployment. The project configuration for BYOC requires you to grant Cockroach Labs permissions to access and modify resources in this project, so this step is necessary to isolate these permissions from non-CockroachDB Cloud resources. This project can be reused for multiple CockroachDB clusters. + +The following requirements apply to the GCP project used for your BYOC deployment: + +- The project ID **must not** begin with the reserved prefix `crl-`. +- [Enable](https://docs.cloud.google.com/endpoints/docs/openapi/enable-api) the Service Usage API and the Cloud Resource Manager APIs for this project. Cockroach Labs will enable additional APIs as needed, but these two must be initialized first. + +## Step 2. Grant permissions to the Cockroach Labs service account + +Cockroach Labs uses cross-account service account impersonation to provision and manage resources in your GCP project. This requires two GCP service accounts: + +- A service account owned by Cockroach Labs which must be granted roles to view and access service accounts in your GCP project. +- An intermediary service account in your GCP project which must be granted roles to create and manage infrasturcture. This service account is the target used by Cockroach Labs for cross-account impersonation, and you specify this service account when creating CockroachDB {{ site.data.products.cloud }} clusters in this organization. + +In this step, use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to collect the email address of the Cockroach Labs service account and grant it the necessary roles. + +Follow these steps to identify the Cockroach Labs service account and grant it the necessary roles: + +1. Send a `GET` request to the `/v1/organization` endpoint of the [CockroachDB {{ site.data.products.cloud }} API](https://www.cockroachlabs.com/docs/api/cloud/v1.html#get-/api/v1/organization) similar to the following example: + {% include_cached copy-clipboard.html %} + ~~~ shell + curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/organization \ + --header 'Authorization: Bearer {secret_key}' + ~~~ + + In the response, the value of `cockroach_cloud_service_principals.gcp.service_account_email` is the email address of the Cockroach Labs service account: + + ~~~ json + { + "cockroach_cloud_service_principals": { + "gcp": { + "service_account_email": "{Cockroach Labs service account}" + } + } + } + ~~~ + +1. Grant this Cockroach Labs service account the following roles in the GCP IAM Console: + - `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` + - `View Service Accounts (roles/iam.serviceAccountViewer)` + +## Step 3. Configure the intermediate service account + +In this step, create the intermediate service account in your GCP project and grant it the necessary roles in your GCP project. + +Follow these steps to create the intermediate service account: + +1. Open the GCP IAM Console. +2. Create a new service account. The account's name is arbitrary and can be whatever you want, but be sure to note down the email address of the account. +3. Grant the following IAM roles to the service account: + - `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)` + - `Compute Network Admin (roles/compute.networkAdmin)` + - `Compute Security Admin (roles/compute.securityAdmin)` + - `Kubernetes Engine Admin (roles/container.admin)` + - `Role Administrator (roles/iam.roleAdmin)` + - `Service Account Admin (roles/iam.serviceAccountAdmin)` + - `Service Account Key Admin (roles/iam.serviceAccountKeyAdmin)` + - `Service Account Token Creator (roles/iam.serviceAccountTokenCreator)` + - `Service Account User (roles/iam.serviceAccountUser)` + - `Logs Configuration Writer (roles/logging.configWriter)` + - `Project IAM Admin (roles/resourcemanager.projectIamAdmin)` + - `Project Mover (roles/resourcemanager.projectMover)` + - `Service Usage Admin (roles/serviceusage.serviceUsageAdmin)` + - `Storage Admin (roles/storage.admin)` + + +## Step 4. Create the CockroachDB {{ site.data.products.cloud }} cluster + +In BYOC deployments, CockroachDB clusters can be deployed in the {{ site.data.products.cloud }} Console or with the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}). + +### Create a cluster with the {{ site.data.products.cloud }} Console + +Follow these steps to create a CockroachDB cluster in the {{ site.data.products.cloud }} console: + +1. Open the {{ site.data.products.cloud }} and select the organization that has been enabled for BYOC. +1. Click **Create cluster**. +1. Under **Select a plan**, click **{{ site.data.products.advanced }}**. +1. Under **Cloud & Regions**, click **Bring Your Own Cloud** and select Google Cloud. +1. Under **Cloud account**, click **Select your cloud account > Add new cloud account**. Enter the service account email associated with the intermediate service account you created, *not* the email address of the Cockroach Labs service account. +1. Follow the rest of the **Create Cluster** steps to configure your cluster's regions, capacity, and features as desired. Read the [Plan a CockroachDB {{ site.data.products.advanced}} Cluster]({% link cockroachcloud/plan-your-cluster-advanced.md %}) documentation for more details. + +### Create a cluster with the {{ site.data.products.cloud }} API + +Send a `POST` request to the the `/v1/clusters` endpoint to [create a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster]({% link cockroachcloud/cloud-api.md %}#create-an-advanced-cluster). + +The following example request creates a 3-node {{ site.data.products.advanced }} cluster in the `us-east1` region, specifying the intermediate service account you created in the `service_account_email` field: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ + --url https://cockroachlabs.cloud/api/v1/clusters \ + --header "Authorization: Bearer {secret_key}" \ + --json '{ + "name": "byoc-gcp-cluster-1", + "plan": "ADVANCED", + "provider": "GCP", + "spec": { + "customer_cloud_account": { + "gcp": { + "service_account_email": "{intermediate_service_account_email}" + } + }, + "dedicated": { + "hardware": { + "machine_spec": { + "num_virtual_cpus": 4 + }, + "storage_gib": 16 + }, + "region_nodes": { + "us-east1": 3 + } + } + } + }' +~~~ + +## Next steps + +- [Connect to your cluster]({% link cockroachcloud/connect-to-an-advanced-cluster.md %}) +- [Manage your cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) +- [Prepare your deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/byoc-overview.md b/src/current/cockroachcloud/byoc-overview.md new file mode 100644 index 00000000000..8ba28990b8b --- /dev/null +++ b/src/current/cockroachcloud/byoc-overview.md @@ -0,0 +1,42 @@ +--- +title: CockroachDB BYOC Overview +summary: Learn about the Bring-Your-Own-Cloud deployment option for CockroachDB +toc: true +keywords: deployment, byoc +--- + +CockroachDB {{ site.data.products.cloud }} supports a [Bring Your Own Cloud (BYOC) deployment model](https://www.cockroachlabs.com/product/cloud/bring-your-own-cloud/), where CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} is hosted in your own cloud account rather than in an account managed by Cockroach Labs. This model allows you to take more control of security and take advantage of existing cloud service credits or discounts. + +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} + +## Shared responsibility model for BYOC + +In any CockroachDB {{ site.data.products.cloud }} deployment, responsibility for a successful and healthy deployment is [split between you and Cockroach Labs]({% link cockroachcloud/production-checklist.md %}). In a BYOC deployment, all of the [CockroachDB {{ site.data.products.cloud }} infrastructure]({% link cockroachcloud/plan-your-cluster-advanced.md %}#advanced-cluster-architecture) except the control plane lives in an account under your control, which means that you incur additional responsibilities under the shared model. + +The following table describes the split of responsibilities between you and Cockroach Labs in the shared responsibility model for BYOC: + +Area | Cockroach Labs responsibility | Customer responsibility +:----------:|:-----------------------------:|:----------------------: +Uptime | Ensure 99.999% cluster uptime | Ensure that clusters remain accessible to CRL via cross-account IAM as documented in the corresponding [deployment guide](#next-steps) +Deployments | Automate cluster provisioning and scaling, provide hardware best practices | Provision new cloud service accounts and grant IAM permissions for Cockroach Labs to create and manage clusters +Upgrades | Provide automatic minor/patch upgrades and major upgrade automation via Terraform, APIs, or the {{ site.data.products.cloud }} Console | Initiate [major version upgrades]({% link cockroachcloud/upgrade-cockroach-version.md %}), [set maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) if applicable +Workload | Troubleshoot problems as they pertain to cluster availability | [Size clusters]({% link cockroachcloud/advanced-cluster-management.md %}#scale-your-cluster) to manage workload requirements, [tune performance]({% link {{ site.versions["stable"] }}/performance-recipes.md %}), and adjust schema designs with support from Cockroach Labs +Backups | Initialize a default backup schedule and write to customer-owned Cloud storage, ensure backup jobs run successfully | Configure a backup schedule as needed to meet RPO/RTO requirements +Support | Reactively and proactively identify and resolve availability-impacting incidents | Ensure sufficient hardware is made available to prevent scaling issues, including negotiating cloud resource quotas and availability with your cloud service provider. Maintain appropriate IAM permissions at all times +Billing | Meter vCPUs consumed, [charge for vCPU consumption]({% link cockroachcloud/costs.md %}) at the per-minute level | Negotiate with cloud service provider, manage infrastructure spend and discounts + +## Next steps + +CockroachDB supports BYOC deployments in Amazon Web Services, Microsoft Azure, and Google Cloud Platform. To prepare your cloud account for a BYOC deployment, refer to the corresponding deployment guide: + +- [Prepare a CockroachDB Cloud BYOC Deployment in Amazon Web Services]({% link cockroachcloud/byoc-aws-deployment.md %}) +- [Prepare a CockroachDB Cloud BYOC Deployment in Azure]({% link cockroachcloud/byoc-azure-deployment.md %}) +- [Prepare a CockroachDB Cloud BYOC Deployment in Google Cloud Platform]({% link cockroachcloud/byoc-gcp-deployment.md %}) + +Once your cloud account is prepared for a BYOC deployment, cluster configuration and management is identical to a CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster. To learn more about CockroachDB {{ site.data.products.cloud }} {{ site.data.products.advanced }} cluster planning and management, refer to the following guides: + +- [Plan an {{ site.data.products.advanced }} cluster deployment]({% link cockroachcloud/plan-your-cluster-advanced.md %}) +- [Manage a cluster using the {{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) +- [Prepare a deployment for production]({% link cockroachcloud/production-checklist.md %}) diff --git a/src/current/cockroachcloud/create-an-advanced-cluster.md b/src/current/cockroachcloud/create-an-advanced-cluster.md index 336901431e5..80047f84ddd 100644 --- a/src/current/cockroachcloud/create-an-advanced-cluster.md +++ b/src/current/cockroachcloud/create-an-advanced-cluster.md @@ -11,10 +11,6 @@ This page guides you through the process of creating a CockroachDB {{ site.data. Only [CockroachDB {{ site.data.products.cloud }} Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) or users with Cluster Creator / Cluster Admin roles assigned at organization scope can create clusters. If you need permission to create a cluster, contact an CockroachDB {{ site.data.products.cloud }} Organization Admin. -{{site.data.alerts.callout_danger}} -If you are creating a cluster for a [BYOC deployment]({% link cockroachcloud/byoc-deployment.md %}) you must use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to perform the actions described on this page. -{{site.data.alerts.end}} - ## Step 1. Start the cluster creation process 1. If you haven't already, sign up for a CockroachDB {{ site.data.products.cloud }} account, then [log in](https://cockroachlabs.cloud/). diff --git a/src/current/cockroachcloud/plan-your-cluster-advanced.md b/src/current/cockroachcloud/plan-your-cluster-advanced.md index 63eb95dbff1..a09a33f7237 100644 --- a/src/current/cockroachcloud/plan-your-cluster-advanced.md +++ b/src/current/cockroachcloud/plan-your-cluster-advanced.md @@ -23,7 +23,7 @@ CockroachDB {{ site.data.products.cloud }} operations are split into logical lay - Control operations manage the CockroachDB cluster as a whole. These requests are handled by the **CockroachDB Cloud control plane** which communicates directly with cluster nodes as needed. These connections include access to the {{ site.data.products.cloud }} Console, DB Console, [Cloud API]({% link cockroachcloud/cloud-api.md %}), [observability features]({% link cockroachcloud/metrics.md %}), and other cluster management tools. - Data operations involve connections between data applications and your underlying CockroachDB nodes, including SQL queries and responses. Each region has a network load balancer (NLB) that handles and distributes requests across CockroachDB nodes within the region. {{ site.data.products.advanced }} clusters can utilize [private connectivity]({% link cockroachcloud/private-clusters.md %}) across the cloud to limit the amount of network traffic that is sent over the public Internet. -In a "bring your own cloud" (BYOC) deployment of CockroachDB {{ site.data.products.cloud }}, the data operations layer is hosted within your own cloud service account rather than an account managed by Cockroach Labs. To learn more, [read the BYOC deployment documentation]({% link cockroachcloud/byoc-deployment.md %}). +In a Bring Your Own Cloud (BYOC) deployment of CockroachDB {{ site.data.products.cloud }}, the data operations layer is hosted within your own cloud service account rather than an account managed by Cockroach Labs. To learn more, [read the BYOC deployment documentation]({% link cockroachcloud/byoc-overview.md %}). ## Cluster topology diff --git a/src/current/v26.1/cockroachdb-feature-availability.md b/src/current/v26.1/cockroachdb-feature-availability.md index 41e060a5705..80782e931f8 100644 --- a/src/current/v26.1/cockroachdb-feature-availability.md +++ b/src/current/v26.1/cockroachdb-feature-availability.md @@ -130,9 +130,9 @@ Exporting metrics to Azure Monitor is in limited access. Refer to [Export metric Enabling and managing [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.advanced }} in the {{ site.data.products.cloud }} Console is in preview. CMEK management with the [Cloud API]({% link cockroachcloud/cloud-api.md %}) is in general availability. -### Bring your own cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} +### Bring Your Own Cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} -Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-deployment.md %}) is in preview for Microsoft Azure. +Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-overview.md %}) is in preview for Amazon Web Services, Microsoft Azure, and Google Cloud Platform. ### Convert a schema from Oracle or Microsoft SQL Server diff --git a/src/current/v26.2/cockroachdb-feature-availability.md b/src/current/v26.2/cockroachdb-feature-availability.md index 74d42a96eb5..efdf16ffff3 100644 --- a/src/current/v26.2/cockroachdb-feature-availability.md +++ b/src/current/v26.2/cockroachdb-feature-availability.md @@ -126,9 +126,9 @@ Exporting metrics to Azure Monitor is in limited access. Refer to [Export metric Enabling and managing [Customer-Managed Encryption Keys (CMEK)]({% link cockroachcloud/cmek.md %}) for CockroachDB {{ site.data.products.advanced }} in the {{ site.data.products.cloud }} Console is in preview. CMEK management with the [Cloud API]({% link cockroachcloud/cloud-api.md %}) is in general availability. -### Bring your own cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} +### Bring Your Own Cloud (BYOC) deployments of CockroachDB {{ site.data.products.cloud }} -Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-deployment.md %}) is in preview for Microsoft Azure. +Deploying CockroachDB {{ site.data.products.cloud }} with a [BYOC deployment model]({% link cockroachcloud/byoc-overview.md %}) is in preview for Amazon Web Services, Microsoft Azure, and Google Cloud Platform. ### Convert a schema from Oracle or Microsoft SQL Server