diff --git a/api-ja/v2/guides/operator-guide-gcp-enclave.md b/api-ja/v2/guides/operator-guide-gcp-enclave.md deleted file mode 100644 index a32839947..000000000 --- a/api-ja/v2/guides/operator-guide-gcp-enclave.md +++ /dev/null @@ -1 +0,0 @@ -このページは移動しました。新しい場所は Unified ID のウェブサイトです: [UID2 Operator - Google Cloud Platform Confidential Computing Package](https://unifiedid.com/ja/docs/guides/operator-guide-gcp-enclave). diff --git a/api/v2/guides/operator-guide-gcp-enclave.md b/api/v2/guides/operator-guide-gcp-enclave.md deleted file mode 100644 index d96eec4a0..000000000 --- a/api/v2/guides/operator-guide-gcp-enclave.md +++ /dev/null @@ -1 +0,0 @@ -This page has been moved. The new location is on the Unified ID website: [UID2 Operator - Google Cloud Platform Confidential Computing Package](https://unifiedid.com/docs/guides/operator-guide-gcp-enclave). diff --git a/docs/guides/operator-guide-aws-marketplace.md b/docs/guides/operator-guide-aws-marketplace.md index 2e01e03a5..d32429987 100644 --- a/docs/guides/operator-guide-aws-marketplace.md +++ b/docs/guides/operator-guide-aws-marketplace.md @@ -2,12 +2,12 @@ title: UID2 Operator - AWS Marketplace Integration sidebar_label: AWS Marketplace pagination_label: UID2 Operator - AWS Marketplace Integration -description: Integration information for AWS Marketplace private operator. +description: Integration information for Private Operator in AWS. hide_table_of_contents: false sidebar_position: 17 --- -# UID2 Operator - AWS Marketplace Integration Guide +# UID2 Operator—AWS Marketplace Integration Guide The UID2 Operator is the API server in the UID2 ecosystem. For a Private Operator service running in AWS Marketplace, the UID2 Operator solution is enhanced with [AWS Nitro](https://aws.amazon.com/ec2/nitro/) Enclave technology. This is an additional security measure to protect UID2 information from unauthorized access. @@ -144,7 +144,7 @@ Here's what you can customize during or after the [deployment](#deployment): | Port Number | Direction | Protocol | Description | | ----------- | --------- | -------- | ------ | -| 80 | Inbound | HTTP | Serves all UID2 APIs, including the healthcheck endpoint `/opt/healthcheck`.
When everything is up and running, the endpoint returns HTTP 200 with a response body of `OK`. For details, see [Checking UID2 Operator Status](#checking-uid2-operator-status).| +| 80 | Inbound | HTTP | Serves all UID2 APIs, including the healthcheck endpoint `/ops/healthcheck`.
When everything is up and running, the endpoint returns HTTP 200 with a response body of `OK`. For details, see [Checking UID2 Operator Status](#checking-uid2-operator-status).| | 9080 | Inbound | HTTP | Serves Prometheus metrics (`/metrics`). | | 443 | Outbound | HTTPS | Calls the UID2 Core Service; updates opt-out data and key store. | diff --git a/docs/guides/operator-guide-azure-enclave.md b/docs/guides/operator-guide-azure-enclave.md index a4bfa833c..4a7d5ce00 100644 --- a/docs/guides/operator-guide-azure-enclave.md +++ b/docs/guides/operator-guide-azure-enclave.md @@ -2,12 +2,12 @@ title: UID2 Operator - Microsoft Azure Confidential Compute Operator Package sidebar_label: Microsoft Azure pagination_label: UID2 Operator - Microsoft Azure Confidential Compute Operator Package -description: Integration information for Microsoft Azure private operator. +description: Integration information for Private Operator in Microsoft Azure. hide_table_of_contents: false sidebar_position: 18 --- -# UID2 Operator - Microsoft Azure Confidential Compute Operator Package +# UID2 Operator—Microsoft Azure Confidential Compute Operator Package >IMPORTANT: This documentation is currently only a proof of concept. For additional guidance, [contact](../getting-started/gs-account-setup.md#contact-info) the UID2 administrator. diff --git a/docs/guides/operator-guide-gcp-enclave.md b/docs/guides/operator-guide-gcp-enclave.md deleted file mode 100644 index 4e24cf519..000000000 --- a/docs/guides/operator-guide-gcp-enclave.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: UID2 Operator - Google Cloud Platform Confidential Computing Package -sidebar_label: Google Cloud Platform -pagination_label: UID2 Operator - Google Cloud Platform Confidential Computing Package -description: Integration information for Google Cloud Platform private operator. -hide_table_of_contents: false -sidebar_position: 20 ---- - -# UID2 Operator - Google Cloud Platform Confidential Computing Package - -This guide provides information for setting up the UID2 Operator Service in a secure enclave in the [Google Cloud](https://cloud.google.com/docs/overview/) platform. - - - -## Overview - -The UID2 Operator service can be run in Google Cloud Platform within a Compute Engine virtual machine (VM) called a [Confidential VM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm), which is a trusted computing enclave. - -The enclave must use a [Container-Optimized OS](https://cloud.google.com/container-optimized-os/docs) boot disk, which can be customized through the provided [cloud-init](https://cloudinit.readthedocs.io/) configuration. - -The `cloud-init` config does the following: -1. Disables remote SSH access to the VM, allowing only UID2 traffic to go in and out. -2. Creates a `systemd` service, which does the following: - 1. Pulls the certified UID2 Operator Docker image from the UID2 project's Docker registry on GitHub (ghcr.io), using `docker pull`. - 2. Starts the container. - -When the UID2 Operator's Docker container starts up, it does the following: -1. Obtains an [instance identity token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity) - a unique JSON Web Token (JWT) that includes details of the VM instance it is running on, as well as Google's RS256 signature. -2. Sends the instance identity token, plus the UID2 `api_token` specified in the `cloud-init` config, to the UID2 Core Service as an Attestation Request. - -When the UID2 Core Service receives the Attestation Request, it verifies the `api_token` and instance identity token. -As part of the Attestation Process for the operator, the UID2 Core Service also sends GCP API calls to retrieve VM instance metadata, such as the boot disk, `cloud-init` config, and audit logs. - -When the attestation is successful, the UID2 Core Service provides seed information such as salts and keys, to bootstrap the UID2 Operator Service. - -## Build - -You can pull the official Docker image to run UID2 Operator on GCP Confidential VM enclave from the GitHub Container Registry location using the following Docker command: - - docker pull ghcr.io/iabtechlab/uid2-operator - -You can build a non-certified UID2 Operator container image from the source code using the following command: - -``` -scripts/gcp/build.sh ghcr.io/iabtechlab/uid2-operator:v1.0.0-snapshot -``` - -## Attestation Requirements - -The UID2 Operator Service can be run on any GCP account and project. However, to support Attestation, the project must grant several -permissions to the service account that the UID2 Core Service uses to issue the GCP API calls during Attestation. - -| Permission | How the UID2 Core Service Uses It | -| :--- | :--- | -| `compute.instances.get` | Retrieves VM instance information, such as `cloud-init` config. | -| `compute.disks.get` | Gets details of the VM boot disk. | -| `logging.logEntries.list` | Lists audit logs for the VM instance. | - -An alternative approach is to grant pre-defined GCP roles to UID2 Core's service account. These roles include the required permissions, as shown in the following table. - -| Role | Permissions Included | -| :--- | :--- | -| `Compute Viewer` | `compute.instances.get`
`compute.disks.get` | -| `Logs Viewer` | `logging.logEntries.list` | - -## Integration Deployment - -You can deploy a new UID2 Operator Service in a GCP VM Enclave into the integration environment by preparing a certified -cloud-init.yaml file for the integration environment, and then create a new Confidential VM that uses the `cloud-init` config. - -This section describes the deployment process. - -### Cloud-init.yaml File -During the registration process, you will be provided with a certified cloud-init-``.yaml file. This file cannot be modified in any way (other than to add the Client API Key) as the sha256sum of the file is used as part of the attestation process. The contents of the file is discussed below, but the file is never created manually during the deployment process - it is always created by the UID team during the process of setting up a new private operator. - -Note that the cloud-init.yaml file is specific to an environment, so you will have one for the integration environment, and one for the production environment. - -### cloud-init Example - -This is the `cloud-init` template to use for deploying UID2 Operator Enclave into the integration environment. This section discusses the contents of the file, but you must use the one provided during the registration process. - -The file content should be provided as custom metadata under the key `user-data` when creating the VM instance. This `user-data` -metadata will be read and interpreted by the Container-Optimized OS (COS) VM disk during -booting. - -As shown in the example below, it first disables remote SSH access, and then tells -COS VM to pull the certified UID2 Operator Docker image from UID2 project's official -Container Registry, using `docker pull`, and run the UID2 Operator container as a `systemd` service. - -In the file you are provided with, the `UID2_ENCLAVE_IMAGE_ID` and `GHCR_RO_ACCESS_TOKEN` values are already set. There is no need to edit them manually. -You will be provided with the UID2_ENCLAVE_API_TOKEN separately, and will need to update this value in the file. - -``` -#cloud-config - -bootcmd: -- iptables -D INPUT -p tcp -m tcp --dport 22 -j ACCEPT -- iptables -A INPUT -p tcp -m tcp --dport 22 -j DROP -- systemctl mask --now serial-getty@ttyS0.service - -runcmd: -- systemctl daemon-reload -- systemctl start uid2-operator.service - -write_files: -- path: /etc/systemd/system/uid2-operator.service - permissions: 0644 - owner: root - content: | - [Unit] - Description=Start UID 2.0 operator as a Docker container - - [Service] - Environment="UID2_ENCLAVE_API_TOKEN=" - Environment="UID2_ENCLAVE_IMAGE_ID=" - Environment="GHCR_RO_ACCESS_TOKEN=" - Environment="HOME=/run/uid2" - ExecStartPre=mkdir -p /run/uid2/.config/gcloud - ExecStartPre=docker login ghcr.io -u gcp-uid2-docker -p ${GHCR_RO_ACCESS_TOKEN} - ExecStartPre=/usr/bin/docker-credential-gcr configure-docker - ExecStart=/usr/bin/docker run --rm --name uid2-operator -v /run/uid2/operator.json:/app/conf/config.json -e KUBERNETES_SERVICE_HOST=1 -e core_api_token=${UID2_ENCLAVE_API_TOKEN} -e optout_api_token=${UID2_ENCLAVE_API_TOKEN} -p 80:8080 ghcr.io/iabtechlab/uid2-operator@sha256:${UID2_ENCLAVE_IMAGE_ID} - ExecStop=/usr/bin/docker stop uid2-operator - ExecStopPost=/usr/bin/docker rm uid2-operator -- path: /run/uid2/operator.json - permissions: 0644 - owner: root - content: | - { - "clients_metadata_path": "https://core-integ.uidapi.com/clients/refresh", - "keys_metadata_path": "https://core-integ.uidapi.com/key/refresh", - "keys_acl_metadata_path": "https://core-integ.uidapi.com/key/acl/refresh", - "salts_metadata_path": "https://core-integ.uidapi.com/salt/refresh", - "core_attest_url": "https://core-integ.uidapi.com/attest", - "optout_metadata_path": "https://optout-integ.uidapi.com/optout/refresh", - "optout_api_uri": "https://optout-integ.uidapi.com/optout/replicate", - "optout_s3_folder": "optout-v2/", - "optout_inmem_cache": true, - "identity_token_expires_after_seconds": 14400, - "refresh_token_expires_after_seconds": 2592000, - "refresh_identity_token_after_seconds": 3600, - "enclave_platform": "gcp-vmid", - "enforce_https": true, - "service_instances": 16, - "allow_legacy_api": false - } -``` - -### Create VM Instance - -To create a new VM instance, follow these steps with the files that you were given during the registration process. - -1. Copy the cloud-init-``.yaml file into a temporary location. -2. Run the [gcloud script](https://cloud.google.com/blog/products/management-tools/scripting-with-gcloud-a-beginners-guide-to-automating-gcp-tasks) file -from the same folder. - This creates a new GCP Confidential VM that uses the correct VM image as well as the `cloud-init` file. - -An example of the `gcloud` script file is: - -``` -$ gcloud compute instances \ - create uid2-operator-gcp-01 \ - --confidential-compute \ - --maintenance-policy Terminate \ - --image https://www.googleapis.com/compute/v1/projects/cos-cloud/global/images/cos-stable-101-17162-40-56 \ - --metadata-from-file user-data=./cloud-init-1674598899.yaml \ - --tags http-server -``` - -You can change the name of the VM (uid2-operator-gcp-01 in the example above), but no other parameters can be changed, or attestation will fail. - -## Production Deployment - -We can deploy a new UID2 Operator in GCP VM Enclave into the production environment by following the same process as for Integration. -You will need a new instance of the cloud-init-``.yaml file. This file uses the production URLs for the UID2 Core Service. -You will also be given a new `gcloud` script file. There are only two differences between the script file for the integration environment and the file for the production environment: -- The name of the cloud-init-``.yaml file used. -- The `machine-type` setting. It is recommended that for the production environment you specify the machine type in the `gcloud` script. Currently, it is recommended that you run the UID2 operator on a machine type of `n2d-standard-16`. - -The following is an example of the script. - -``` -$ gcloud compute instances \ - create uid2-operator-gcp-01 \ - --machine-type n2d-standard-16 \ - --confidential-compute \ - --maintenance-policy Terminate \ - --image https://www.googleapis.com/compute/v1/projects/cos-cloud/global/images/cos-stable-101-17162-40-56 \ - --metadata-from-file user-data=./cloud-init-1674598899.yaml \ - --tags http-server -``` - ->NOTE: Compared to the `gcloud` command used in the prior section, an additional option, `--machine-type n2d-standard-16`, is added. This option ensures that the production deployment of the UID2 Operator Service runs on -the recommended machine type that matches the production configuration. - -## Upgrading - -For each operator version update, private operators receive an email notification with an upgrade window, after which the old version is deactivated and no longer supported. -To upgrade to the latest version, deploy the new `cloud-init` configuration provided in the email in the same way as you deployed the original operator. \ No newline at end of file diff --git a/docs/guides/operator-private-gcp-confidential-space.md b/docs/guides/operator-private-gcp-confidential-space.md new file mode 100644 index 000000000..5990d5f1a --- /dev/null +++ b/docs/guides/operator-private-gcp-confidential-space.md @@ -0,0 +1,486 @@ +--- +title: UID2 Operator - Google Cloud Platform Confidential Space +sidebar_label: GCP Confidential Space +pagination_label: UID2 Operator - Google Cloud Platform Confidential Space +description: Integration information for Private Operator in GCP. +hide_table_of_contents: false +sidebar_position: 18 +--- + +# UID2 Private Operator—Google Cloud Platform Confidential Space + +This guide provides information for setting up the UID2 Operator Service in [Confidential Space](https://cloud.google.com/confidential-computing#confidential-space), a confidential computing option from [Google Cloud](https://cloud.google.com/docs/overview/) Platform. Confidential Space offers a secure enclave environment, known as a Trusted Execution Environment (TEE). + +>NOTE: The UID2 Private Operator implementation for GCP Confidential Space is not supported in these areas: Europe, China. + +The Operator Service runs in a Confidential Space "workload"—a containerized Docker image that runs in a secure cloud-based enclave on top of the Confidential Space image. + +When the Docker container for the UID2 Operator Confidential Space starts up, it completes the attestation process that allows the UID2 Core Service to verify the authenticity of the Operator Service and the enclave environment that the Operator Service is running in. + +When the attestation is successful, the UID2 Core Service provides seed information such as salts and keys to bootstrap the UID2 Operator in the secure Confidential Space container. + +## Setup Overview + +At a high level, the setup steps are as follows: + +1. Create your Confidential Space and UID2 Operator accounts and get, or create, the various values that you'll need for configuration and deployment: see [Prerequisites](#prerequisites). +1. Review information about [deployment environments](#deployment-environments). + + Best practice is to deploy in the integration environment first, and then the production environment. +1. Review information about the [deployment options](#deployment-options) available, including the benefits of each, and decide which to use. + + We recommend the Terraform template option. +1. Follow the applicable instructions for the deployment option you chose, out of the following: + - [Terraform Template](#deployterraform-template) + - [gcloud CLI](#deploygcloud-cli) + +When all steps are complete, your implementation should be up and running. + +## Prerequisites + +Before setting up your UID2 Operator Service in the Google Cloud Platform using Confidential Space, complete these prerequisite steps: + +- [Confidential Space Account Setup](#confidential-space-account-setup) +- [UID2 Operator Account Setup](#uid2-operator-account-setup) + +### Confidential Space Account Setup + +You can run the UID2 Operator Service on any GCP account and project. However, to support attestation, you'll need to create a service account that you can use to run Confidential Space virtual machines (VMs). + +Before choosing your deployment option, complete these Google Cloud setup steps: + +1. Create the GCP project that you want the UID2 Operator to run in. We recommend creating a new project for the UID2 Operator Service, but you could also use an existing one. Follow these guidelines: + + - Choose a project name; for example, `UID2-Operator-Production`. You'll use this as the `{PROJECT_ID}` value in later steps. + - Make sure that you define a GCP project with billing enabled. + +1. Choose a name for the GCP service account that you'll use to run Confidential Space VMs; for example, `uid2-operator`. You'll use this as the `{SERVICE_ACCOUNT_NAME}` value in later steps. + +1. Install the gcloud CLI, required by both deployment options. Follow the instructions provided by Google: [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install). + +### UID2 Operator Account Setup +Ask your UID2 contact to register your organization as a UID2 Operator. If you're not sure who to ask, see [Contact Info](../getting-started/gs-account-setup.md#contact-info). + +>TIP: It's a good idea to set up an internal email distribution list of individuals who should be kept informed about new versions and any other technical notifications or requests, and provide that as the email contact. + +When the registration process is complete, you'll receive the following: + +| Item | Description | +| :--- | :--- | +| `{OPERATOR_IMAGE}` | The Docker image URL for the UID2 Private Operator for GCP, used in configuration. The following example is fictitious, but shows what the Docker image URL might look like: `https://console.cloud.google.com/artifacts/docker/uid2-prod-project/us/iabtechlab/uid2-operator/sha256:2e4fae98b688002303c6263f7c4bf95344a1d9c15fb5fcf838b59032bb9813f2`. Use the image URL provided to you as part of account setup.
NOTE: The image is valid for both deployment environments. | +| `{OPERATOR_KEY}` | An operator key, exclusive to you, that identifies you with the UID2 service as a private operator. Use this as the `OPERATOR_KEY` value during configuration. This value is both your unique identifier and a password; store it securely and do not share it.
NOTE: You'll receive a separate operator key for each deployment environment. | +| Instructions | Additional information details, such as instructions for setting up VMs or a link to the applicable information. | + +When UID2 account registration is complete, and you've installed the gcloud CLI, your next steps are: +- Review information about [deployment environments](#deployment-environments). +- Review information about the [deployment options](#deployment-options) available, including the benefits of each, and decide which to use. + +## Deployment Environments + +The following environments are available, and both [deployment options](#deployment-options) support both environments. + +As a best practice, we recommend that you test and verify your implementation in the integration environment before deploying in the production environment. + +>NOTE: You'll receive separate `{OPERATOR_KEY}` values for each environment. Be sure to use the correct one. The `{OPERATOR_IMAGE}` value is the same for both environments. + +| Environment | Details | +| :--- | :--- | +| Integration (`integ`) | For testing only. Debug mode is available in the integration environment. | +| Production (`prod`) | For managing production traffic. For this environment, we recommend deploying via the Terraform template, with load balancing, and with HTTPS enabled. See [Deployment Options](#deployment-options). | + +## Deployment Options + +There are two deployment options: + +| Option | Details | +| :--- | :--- | +| [Terraform template](#deployterraform-template) | This option:
  • Does not require manually setting up a service account. The setup is very simple.
  • Brings up a whole stack with a load balancer and a scaling group.
  • Is easier to maintain and operate than the `gcloud` option.
  • Is very simple to upgrade.
  • Is the recommended deployment solution.
| +| [gcloud CLI](#deploygcloud-cli) | This option:
  • Brings up one VM instance with a public IP address.
  • Can be easier for quick experimentation/evaluation.
  • For multiple instances, requires bringing up each instance manually, by running the command multiple times.
  • Requires setting up the load balancer manually.
  • Is more complex to upgrade, since more manual steps are needed.
| + +Both deployment options support both deployment environments. + +To determine your next steps, choose the deployment option you want to use. Then, follow the applicable instructions: +- [Deploy—Terraform Template](#deployterraform-template) +- [Deploy—gcloud CLI](#deploygcloud-cli) + +### Deploy—Terraform Template + +For ease of deployment and upgrade, you can use a Terraform template to deploy a UID2 Private Operator implementation with load balancing and auto-scaling features. In this scenario, all VM instances run on Confidential Space VMs, and are deployed in multiple availability zones (AZs). + +The Terraform template does the following: +- Activates the required Google Cloud Platform APIs. +- Sets up a service account to run Confidential Space VMs. +- Creates a secret to hold the `operator_key` value. +- Creates the following components: + - Network: VPC and subnetwork. + - Instances: Instance template, instance groups (with auto-scaling enabled). + - Ingress: Load balancer (with health check), forwarding rules, and firewall rules. + - Egress: [Cloud Network Address Translation (NAT)](https://cloud.google.com/nat/docs/overview). +- If HTTPS is enabled, provides your HTTPS certificate to Terraform. + +>NOTE: The Terraform template uses the gcloud CLI that you installed in [Confidential Space Account Setup](#confidential-space-account-setup) Step 3. + +To deploy a new UID2 Operator in the GCP Confidential Space Enclave, using the Terraform template, follow these steps: + +1. [Install Terraform](#install-terraform) +1. [Set Up the Terraform Environment](#set-up-the-terraform-environment) +1. [Download the Template Files](#download-the-template-files) +1. [Provide Input Values](#provide-input-values) +1. [Run Terraform](#run-terraform) +1. [Test Terraform Using the Health Check Endpoint](#test-terraform-using-the-health-check-endpoint) + +For additional information, see: +- [Delete All Created Resources](#delete-all-created-resources) +- [Outputs](#outputs) + +#### Install Terraform + +Install Terraform if it is not already installed: visit [terraform.io](https://www.terraform.io/). + +#### Set Up the Terraform Environment + +1. Create a new project or select an existing one, replacing the `{PROJECT_ID}` placeholder with your own project ID (see [Confidential Space Account Setup](#confidential-space-account-setup)): + + ``` + gcloud config set project {PROJECT_ID} + ``` + +2. Configure the environment for Terraform: + + ``` + gcloud auth application-default login + ``` + +#### Download the Template Files + +Follow the instructions you receive when your registration process is complete (see [UID2 Operator Account Setup](#uid2-operator-account-setup)) to download the template files listed in the following table. + +| File | Details | +| :--- | :--- | +| `main.tf` | The Terraform template file. | +| `variables.tf` | Contains the definitions for the template input variables, including name, type, and default value. | +| `outputs.tf` | Includes output definitions. | +| `terraform.tfvars` | Contains the values for the template input variables. | + +#### Provide Input Values + +Provide values for the input parameters, as needed, in the `terraform.tfvars` file that you downloaded. Some are required, others are optional. + +1. Provide values for the required input parameters shown in the following table: + + | Name | Type | Default | Required | Description | + | :--- | :--- | :--- | :--- | :--- | + | `project_id` | `string` | n/a | yes | The ID of the GCP project that you want the UID2 Operator to run in; for example, `UID2-Operator-Production`. | + | `service_account_name` | `string` | n/a | yes | The name of the service account that you want to use for your UID2 Operator instance in GCP Confidential Space. | + | `uid_operator_image` | `string` | n/a | yes | The Docker image URL for the UID2 Private Operator for GCP, used in configuration, which you received as part of [UID2 Operator Account Setup](#uid2-operator-account-setup). For example: `us-docker.pkg.dev/uid2-prod-project/iabtechlab/uid2-operator@sha256:{IMAGE_SHA}`. | + | `uid_operator_key` | `string` | n/a | yes | The UID2 operator key, which you received as part of [UID2 Operator Account Setup](#uid2-operator-account-setup). | + | `uid_deployment_env` | `string` | `integ` | yes | Valid values: `integ` for integration environment, `prod` for production environment.
Machine type is determined by the deployment environment: `integ` uses `n2d-standard-2` and `prod` uses `n2d-standard-16`. | + +1. (Optional, strongly recommended) Set the load balancer to HTTPS. Provide values for the parameters shown in the following table: + + | Name | Type | Default | Required | Description | + | :--- | :--- | :--- | :--- | :--- | + | `ssl` | `bool` | `false`| no | To set the load balancer to use HTTPS, which is recommended, set this flag to `true`.
If you're using HTTPS you must also specify values for the `certificate` and `private_key` parameters. | + | `certificate` | `string` | n/a | no | The contents of the HTTPS certificate. The certificate should be in PEM format.
For example: `file('path/to/certificate.pem')`.
Required if `ssl` is set to `true`.
For details, see [google_compute_ssl_certificate](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_ssl_certificate#certificate) in the Terraform documentation. | + | `private_key` | `string` | n/a | no | The contents of the private key for the HTTPS certificate. The private key should be in PEM format.
For example: `file('path/to/private_key.pem')`.
Required if `ssl` is set to `true`.
For details, see [google_compute_ssl_certificate](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_ssl_certificate#private_key) in the Terraform documentation. | + +1. (Optional) Provide parameter names and values for the additional input parameters shown in the following table. These parameters are always optional, but you might want to modify from the default values to better suit your requirements. + + | Name | Type | Default | Required | Description | + | :--- | :--- | :--- | :--- | :--- | + | `region` | `string` | `us-east1` | no | The region that you want to deploy to. For a list of valid regions, see [Available regions and zones](https://cloud.google.com/compute/docs/regions-zones#available) in the Google Cloud documentation.
NOTE: The UID2 Private Operator implementation for GCP Confidential Space is not supported in these areas: Europe, China. | + | `network_name` | `string` | `uid-operator` | no | The VPC resource name (also used for rules/ instance tags). | + | `min_replicas` | `number` | `1` | no | Indicates the minimum number of replicas you want to deploy. | + | `max_replicas` | `number` | `5` | no | Indicates the maximum number of replicas you want to deploy. | + | `uid_operator_key_secret_name` | `string` | `"secret-operator-key"` | no | The name that you specify for your operator key secret. The Terraform template creates a secret in the GCP Secret Manager to hold the `uid_operator_key` value. You can define the name; for example, `uid2-operator-operator-key-secret-integ`. | + | `debug_mode` | `bool` | `false` | no | Do not set to `true` unless you are working with the UID2 team to debug an issue. In any other circumstances, if you set this flag to `true`, attestation will fail. | + +#### Run Terraform + +Run the following: + +``` +terraform init +terraform apply +``` +When you run `terraform apply`, the following file is generated in the same folder: [`terraform.tfstate`](https://developer.hashicorp.com/terraform/language/state). This file stores state information about your managed infrastructure and configuration. + +This file will be used for future maintenance. Be sure to persist it remotely. + +#### Test Terraform Using the Health Check Endpoint + +Call the health check endpoint to test the health of your implementation. The expected result is HTTP 200 with a response body of `OK`. + +For instructions, see [Health Check—Terraform Template](#health-checkterraform-template). + +#### Delete All Created Resources + +In a scenario where you want to clean up, you can remove the resources created by the template. For example, you might want to test `integ` and remove the whole stack later. + +To remove all resources created by Terraform, run the following: + +``` +terraform destroy +``` + +#### Outputs + +The following table summarizes the output value from the Terraform template. + +| Name | Description | +| :--- | :--- | +| `load_balancer_ip` | The public IP address of the load balancer.
You can use this value to [perform the health check](#health-checkterraform-template) or to configure the DNS. | + +### Deploy—gcloud CLI + +To deploy a new UID2 Operator in the GCP Confidential Space Enclave using the gcloud CLI, follow these steps. + +>NOTE: For deployment to the production environment we do not recommend this option. We recommend deploying via the Terraform template, with load balancing, and with HTTPS enabled. + + 1. [Set Up Service Account Rules and Permissions](#set-up-service-account-rules-and-permissions) + 1. [Create Secret for the Operator Key in Secret Manager](#create-secret-for-the-operator-key-in-secret-manager) + 1. [Update the Script with Valid Values](#update-the-script-with-valid-values) + 1. [Run the Script](#run-the-script) + 1. [Test gcloud Using the Health Check Endpoint](#test-gcloud-using-the-health-check-endpoint) + +#### Set Up Service Account Rules and Permissions + +To set up and configure the account that you created when you installed the gcloud CLI, complete the following steps. Replace the placeholder values with your own valid values. + +1. Switch to the project that you created in [Confidential Space Account Setup](#confidential-space-account-setup): + ``` + $ gcloud config set project {PROJECT_ID} + ``` + +1. Enable the following APIs: + + | Name | Description | + | :--- | :--- | + | compute.googleapis.com | Compute Engine API | + | confidentialcomputing.googleapis.com | Confidential Computing API | + | logging.googleapis.com | Cloud Logging API | + | secretmanager.googleapis.com | Service Management API | + + Run this command to enable the APIs: + + ``` + $ gcloud services enable compute.googleapis.com \ + confidentialcomputing.googleapis.com \ + logging.googleapis.com \ + secretmanager.googleapis.com + ``` + +1. Create a service account to run the UID2 Operator Service: + ``` + $ gcloud iam service-accounts create {SERVICE_ACCOUNT_NAME} + ``` + +1. Grant the required permissions to the service account. + + Permissions are shown in the following table. + + | Permission | Description | + | :--- | :--- | + | `confidentialcomputing.workloadUser` | Provides the permission to generate an attestation token and run a workload in a VM. | + | `logging.logWriter` | Provides the permission to write log entries in gcloud logging. | + | `secretmanager.secretAccessor` | Provides the permission to access the operator key that is managed in the GCP Secret Manager. | + + Grant the `confidentialcomputing.workloadUser` permission: + + ``` + $ gcloud projects add-iam-policy-binding {PROJECT_ID} \ + --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ + --role=roles/confidentialcomputing.workloadUser + ``` + Grant the `logging.logWriter` permission: + + ``` + $ gcloud projects add-iam-policy-binding {PROJECT_ID} \ + --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ + --role=roles/logging.logWriter + ``` + + Grant the `secretmanager.secretAccessor` permission: + + ``` + $ gcloud projects add-iam-policy-binding {PROJECT_ID} \ + --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ + --role=roles/secretmanager.secretAccessor + ``` + +1. Add a VPC rule to allow public access on port 8080, the default exposed port for the UID2 operator: + ``` + $ gcloud compute firewall-rules create operator-tcp \ + --direction=INGRESS --priority=1000 --network=default --action=ALLOW \ + --rules=tcp:8080 \ + --source-ranges=0.0.0.0/0 \ + --target-service-accounts={SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com + ``` + +#### Create Secret for the Operator Key in Secret Manager + +As part of setting up your UID2 account (see [UID2 Operator Account Setup](#uid2-operator-account-setup)), you'll receive an operator key for each environment. + +The next step is to store the `{OPERATOR_KEY}` value in GCP Secret Manager and get a full secret name for it, which you later use to replace the `{OPERATOR_KEY_SECRET_FULL_NAME}` placeholder in the deployment script (see [Update the Script with Valid Values](#update-the-script-with-valid-values)). + +Follow these steps: + 1. Run the following script, which creates a new secret, first customizing with your own values: + + ``` + OPERATOR_KEY="{OPERATOR_KEY}" + echo -n $OPERATOR_KEY | gcloud secrets create {OPERATOR_KEY_SECRET_NAME} \ + --replication-policy="automatic" \ + --data-file=- + ``` + + 1. Prepare the script, using your own values: + + - For `{OPERATOR_KEY}`, use your own operator key value for the environment. + - For `{OPERATOR_KEY_SECRET_NAME}`, specify the name you want to use for your API secret, for this environment. For example: `uid2-operator-operator-key-secret-integ`. + + 2. Run the script. + + The script creates the secret in GCP Secret Manager. The secret (display) name is {OPERATOR_KEY_SECRET_NAME} and the secret value is {OPERATOR_KEY}. + +1. Run the following command to get the full secret name, including the path, first customizing with your own values: + + ``` + $ gcloud secrets versions describe latest --secret {OPERATOR_KEY_SECRET_NAME} --format 'value(name)' + ``` + +In this example, the full secret name might be: `projects/111111111111/secrets/uid2-operator-operator-key-secret-integ/versions/1`. This is the value that you would use to replace the `{OPERATOR_KEY_SECRET_FULL_NAME}` placeholder in the next section. + +#### Update the Script with Valid Values + +Update the example script, using your own valid values instead of the placeholder values. + +This section includes: + +- [Placeholder Values and Definitions](#placeholder-values-and-definitions) +- [Sample Deployment Script—Integ](#sample-deployment-scriptinteg) +- [Sample Deployment Script—Prod](#sample-deployment-scriptprod) + +##### Placeholder Values and Definitions + +Placeholder values are defined in the following table. + +| Placeholder | Actual Value | +| :--- | :--- | +| `{INSTANCE_NAME}` | Your own valid VM name. | +| `{ZONE}` | The Google Cloud zone that the VM instance will be deployed on. | +| `{SERVICE_ACCOUNT}` | The service account email that you created as part of creating your account, in this format: `{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com`.
For details, see [Set Up Service Account Rules and Permissions](#set-up-service-account-rules-and-permissions) (Step 4). | +| `{OPERATOR_IMAGE}` | The Docker image URL for the UID2 Private Operator for GCP, used in configuration.
For details, see [UID2 Operator Account Setup](#uid2-operator-account-setup). | +| `{OPERATOR_KEY_SECRET_FULL_NAME}` | The full name that you specified for the Operator Key secret (see [Create Secret for the Operator Key in Secret Manager](#create-secret-for-the-operator-key-in-secret-manager)), including the path, in the format `projects//secrets//versions/`. For example: `projects/111111111111/secrets/uid2-operator-operator-key-secret-integ/versions/1`. | + +##### Sample Deployment Script—Integ + +The following example of the deployment script for the integration environment uses some placeholder values. + +``` +$ gcloud compute instances create {INSTANCE_NAME} \ + --zone {ZONE} \ + --machine-type n2d-standard-2 \ + --confidential-compute \ + --shielded-secure-boot \ + --maintenance-policy Terminate \ + --scopes cloud-platform \ + --image-project confidential-space-images \ + --image-family confidential-space \ + --service-account {SERVICE_ACCOUNT} \ + --metadata ^~^tee-image-reference={OPERATOR_IMAGE}~tee-restart-policy=Never~tee-env-DEPLOYMENT_ENVIRONMENT=integ~tee-env-API_TOKEN_SECRET_NAME={OPERATOR_KEY_SECRET_FULL_NAME} +``` + +##### Sample Deployment Script—Prod + +The following example of the deployment script for the production environment uses some placeholder values. + +>NOTE: A `machine-type` value of `n2d-standard-16` is required for the production environment. + +``` +$ gcloud compute instances create {INSTANCE_NAME} \ + --zone {ZONE} \ + --machine-type n2d-standard-16 \ + --confidential-compute \ + --shielded-secure-boot \ + --maintenance-policy Terminate \ + --scopes cloud-platform \ + --image-project confidential-space-images \ + --image-family confidential-space \ + --service-account {SERVICE_ACCOUNT} \ + --metadata ^~^tee-image-reference={OPERATOR_IMAGE}~tee-restart-policy=Never~tee-env-DEPLOYMENT_ENVIRONMENT=prod~tee-env-API_TOKEN_SECRET_NAME={OPERATOR_KEY_SECRET_NAME} +``` + +#### Run the Script + +When the script is ready, with the additional valid values, run it. + +#### Test gcloud Using the Health Check Endpoint + +Call the health check endpoint to test the health of your implementation. The expected result is HTTP 200 with a response body of `OK`. + +For instructions, see [Health Check—gcloud CLI](#health-checkgcloud-cli). + +## Tasks + +This section provides instructions for completing the following tasks. Where applicable, instructions are provided for both environments. It includes: + +- [Running the Health Check](#running-the-health-check) +- [Upgrading](#upgrading) + +### Running the Health Check + +Call the health check endpoint to test the health of your implementation. + +Running the health check is the same for the integration and production environments, except for the endpoints. + +Follow the applicable instructions depending on the deployment option you chose: + +- [Health Check—Terraform Template](#health-checkterraform-template) +- [Health Check—gcloud CLI](#health-checkgcloud-cli) + +#### Health Check—Terraform Template + +The following example shows the health check for the Terraform template option: + +1. Get the public IP address for the load balancer: + + ``` + terraform output load_balancer_ip + ``` + +2. To test operator status, in your browser, go to the health check endpoint: `http://{IP}/ops/healthcheck`. + + An HTTP 200 with a response body of `OK` indicates healthy status. + + +#### Health Check—gcloud CLI +The following example shows the health check for the `gcloud` command line option: + +1. Get the public IP address of the deployed instance: + + ``` + $ gcloud compute instances describe {INSTANCE_NAME} \ + --format='get(networkInterfaces[0].accessConfigs[0].natIP)' + ``` +2. To test operator status, in your browser, go to `http://{IP}:8080/ops/healthcheck`. + + An HTTP 200 with a response body of `OK` indicates healthy status. + +### Upgrading + +When a new version of UID2 Google Cloud Platform Confidential Space is released, private operators receive an email notification of the update, with a new image version. There is a window of time for upgrade, after which the older version is deactivated and is no longer supported. + +If you're upgrading to a new version, the upgrade process depends on the deployment option you chose. Follow the applicable steps: + +- [Upgrading—Terraform Template](#upgradingterraform-template) +- [Upgrading—gcloud CLI](#upgradinggcloud-cli) + +#### Upgrading—Terraform Template + +If you deployed using the Terraform template, all you need to do to upgrade is update your deployment with the new `{OPERATOR_IMAGE}` that you received in the upgrade notification. + +#### Upgrading—gcloud CLI + +If you deployed using the gcloud CLI, you must manually bring up new instances that use the new `{OPERATOR_IMAGE}` and then shut down old instances. + +If you previously set up a load balancer manually, you'll also need to update the mapping for the load balancer. diff --git a/docs/guides/summary-guides.md b/docs/guides/summary-guides.md index 62368bd8a..b98ef84e9 100644 --- a/docs/guides/summary-guides.md +++ b/docs/guides/summary-guides.md @@ -88,6 +88,6 @@ The following resources are available for Private Operator integrations. | Integration Guide | Content Description | | :--- | :--- | -| [UID2 Operator - AWS Marketplace](operator-guide-aws-marketplace.md) | Instructions for setting up a Private Operator service for AWS Marketplace. | -| [UID2 Operator - Google Cloud Platform Confidential Computing package](operator-guide-gcp-enclave.md) | Instructions for setting up the Google Cloud Platform Confidential Computing package (GCP). | -| [UID2 Operator - Microsoft Azure Confidential Compute Operator Package](operator-guide-azure-enclave.md) | IMPORTANT: This documentation is currently only a proof of concept. For additional guidance, [contact](../getting-started/gs-account-setup.md#contact-info) the UID2 administrator.
Instructions for setting up a Private Operator service for running on Microsoft Azure Confidential Computing platform. | +| [UID2 Operator—AWS Marketplace](operator-guide-aws-marketplace.md) | Instructions for setting up a Private Operator service for AWS Marketplace. | +| [UID2 Private Operator—Google Cloud Platform Confidential Space](operator-private-gcp-confidential-space.md) | Information for setting up the UID2 Operator Service in [Confidential Space](https://cloud.google.com/confidential-computing#confidential-space), a confidential computing option from [Google Cloud](https://cloud.google.com/docs/overview/) Platform. | +| [UID2 Operator—Microsoft Azure Confidential Compute Operator Package](operator-guide-azure-enclave.md) | IMPORTANT: This documentation is currently only a proof of concept. For additional guidance, [contact](../getting-started/gs-account-setup.md#contact-info) the UID2 administrator.
Instructions for setting up a Private Operator service for running on Microsoft Azure Confidential Computing platform. | diff --git a/docs/overviews/overview-operators-private.md b/docs/overviews/overview-operators-private.md index 763c692d5..ee1393a71 100644 --- a/docs/overviews/overview-operators-private.md +++ b/docs/overviews/overview-operators-private.md @@ -39,7 +39,7 @@ The following documentation resources are available for private operators to imp | Integration Type| Documentation | Content Description | Audience | | :--- | :--- | :--- | :--- | | Operator | [UID2 Operator - AWS Marketplace Integration Guide](../guides/operator-guide-aws-marketplace.md) | Instructions for setting up a Private Operator service for AWS Marketplace. | Private Operators | -| GCP| [UID2 Operator - Google Cloud Platform Confidential Computing package](../guides/operator-guide-gcp-enclave.md) | Instructions for setting up the Google Cloud Platform Confidential Computing package (GCP). | Private Operators | +| GCP Confidential Space | [UID2 Private Operator—Google Cloud Platform Confidential Space](../guides/operator-private-gcp-confidential-space.md) | Information for setting up the UID2 Operator Service in [Confidential Space](https://cloud.google.com/confidential-computing#confidential-space), a confidential computing option from [Google Cloud](https://cloud.google.com/docs/overview/) Platform. | Private Operators | | Azure | [UID2 Operator - Microsoft Azure Confidential Compute Operator Package](../guides/operator-guide-azure-enclave.md) | IMPORTANT: This documentation is currently only a proof of concept. For additional guidance, [contact](../getting-started/gs-account-setup.md#contact-info) the UID2 administrator.
Instructions for setting up a Private Operator service for running on Microsoft Azure Confidential Computing platform. | Private Operators | ## Getting Started diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index bbdc2e41e..50cb2c874 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -149,9 +149,9 @@ sidebar_position: 10
Enclave
An enclave is a secure subsection of a computing environment. The enclave has additional business logic and security measures applied to it, to prevent anyone from tampering with it.
In the context of UID2, a private operator must run inside an enclave or in a private environment. The enclave versions supported are:
-- AWS Nitro: see UID2 Operator - AWS Marketplace Integration Guide.
-- Google Cloud Platform Confidential Computing: see UID2 Operator - Google Cloud Platform Confidential Computing Package.
-- Microsoft Azure confidential computing: see Microsoft Azure Confidential Compute Operator Package.
+- AWS Nitro: see UID2 Operator—AWS Marketplace Integration Guide.
+- Google Cloud Platform Confidential Space: see UID2 Operator—Google Cloud Platform Confidential Space.
+- Microsoft Azure confidential computing: see UID2 Operator—Microsoft Azure Confidential Compute Operator Package.
In an enclave, the operator image must be a very specific, predefined version, and additional constraints are applied to ensure security.
First-level hash
@@ -167,8 +167,6 @@ sidebar_position: 10
JSON Web Token (JWT)
A JSON Web Token (JWT) is a compact, URL-safe means of representing claims (pieces of information) to be sent from one party to another over the web. The claims in a JWT are encoded as a JSON object that is used either as the payload of a JSON Web Signature (JWS) structure or as the plain text of a JSON Web Encryption (JWE) structure. This enables the claims to be digitally signed and/or encrypted.
-
UID2 uses JSON Web Tokens as part of interfacing with the Google Cloud Platform (GCP) Enclave.
-
For details, see UID2 Operator - Google Cloud Platform Confidential Compute package.
Normalize
To normalize a data set means to bring it to a standard condition or state.
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-aws-marketplace.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-aws-marketplace.md index 36368ff8f..f4d9d91b9 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-aws-marketplace.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-aws-marketplace.md @@ -1,5 +1,7 @@ --- title: UID2 Operator - AWS Marketplace Integration +sidebar_label: AWS Marketplace +pagination_label: UID2 Operator - AWS Marketplace Integration description: AWS Marketplace Private Operator のインテグレーション情報。 hide_table_of_contents: false sidebar_position: 17 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-azure-enclave.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-azure-enclave.md index ef6436838..80b30dca5 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-azure-enclave.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-azure-enclave.md @@ -1,5 +1,7 @@ --- title: UID2 Operator - Microsoft Azure Confidential Compute Operator Package +sidebar_label: Microsoft Azure +pagination_label: UID2 Operator - Microsoft Azure Confidential Compute Operator Package description: Microsoft Azure Private Operator のインテグレーション情報。 hide_table_of_contents: false sidebar_position: 18 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-gcp-enclave.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-gcp-enclave.md deleted file mode 100644 index 4a808f0ec..000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-guide-gcp-enclave.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: UID2 Operator - Google Cloud Platform Confidential Computing Package -description: Google Cloud Platform Private Operator のインテグレーション情報。 -hide_table_of_contents: false -sidebar_position: 20 ---- - -# UID2 Operator - Google Cloud Platform Confidential Computing Package - -本ガイドでは、[Google Cloud](https://cloud.google.com/docs/overview/) Platform のセキュアなエンクレーブで UID2 Operator Service を設定するための情報を提供します。 - - - -## Overview - -UID2 Operator サービスは、Google Cloud Platform の[Confidential VM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm)と呼ばれる Compute Engine の仮想マシン (VM)内で実行できます。これは、トラステッド・コンピューティング・エンクレーブです。 - -エンクレーブは、[Container-Optimized OS](https://cloud.google.com/container-optimized-os/docs) ブートディスクを使用する必要があり、提供される [cloud-init](https://cloudinit.readthedocs.io/) config によりカスタマイズできます。 - -`cloud-init` config は以下を行います: - -1. VM へのリモート SSH アクセスを無効化し、UID2 トラフィックの in/out のみを許可します。 -2. `systemd` サービスを作成し、以下の処理を行います: - 1. UID2 プロジェクトの Docker レジストリから、`docker pull`を使って、GitHub (ghcr.io)の UID2 Operator 認定 Docker イメージを取り込みます。 - 2. コンテナを起動します。 - -UID2 Operator の Docker コンテナが起動すると、次のような処理が行われます: - -1. [instance identity token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity)を取得します。これは、実行中の VM インスタンスの詳細と Google の RS256 署名を含む一意の JSON Web Token(JWT)です。 -2. instance identity token と、`cloud-init` config で指定した UID2 `api_token` を、UID2 Core Service に認証リクエストとして送ります。 - -UID2 Core Service は認証リクエストを受信すると、`api_token`と instance identity token を検証します。オペレーターの認証プロセスの一環として、UID2 Core Service は GCP API コールを送信し、起動ディスク、`cloud-init` config、監査ログなど、VM インスタンスのメタデータを取得します。 - -認証に成功すると、UID2 Core Service は UID2 Operator Service を起動するために、Salt や Key などのシード情報を提供します。 - -## Build - -GCP Confidential VM エンクレーブ上で UID2 Operator を実行するための公式 Docker イメージは、以下の Docker コマンドで GitHub Container Registry から取得できます: - -``` -docker pull ghcr.io/iabtechlab/uid2-operator -``` - -以下のコマンドで、ソースコードから非認証の UID2 Operator コンテナイメージをビルドできます: - -``` -scripts/gcp/build.sh ghcr.io/iabtechlab/uid2-operator:v1.0.0-snapshot -``` - -## Attestation Requirements - -UID2 Operator Service は、どの GCP アカウントおよびプロジェクトでも実行できます。ただし、認証をサポートするために、プロジェクトは、UID2 Core Service が認証中に GCP API コールを発行するために使用するサービスアカウントに、いくつかの権限を付与する必要があります。 - -| Permission | How the UID2 Core Service Uses It | -| :------------------------ | :----------------------------------------------------------- | -| `compute.instances.get` | `cloud-init` の設定など、VM インスタンスの情報を取得します。 | -| `compute.disks.get` | VM の起動ディスクの詳細を取得します。 | -| `logging.logEntries.list` | VM インスタンスの監査ログをリストアップします。 | - -別の方法として、UID2 Core のサービスアカウントにあらかじめ定義された GCP ロールを付与することもできます。これらのロールには、次の表に示すように、必要な権限が含まれています。 - -| Role | Permissions Included | -| :--------------- | :---------------------------------------------- | -| `Compute Viewer` | `compute.instances.get`
`compute.disks.get` | -| `Logs Viewer` | `logging.logEntries.list` | - -## Integration Deployment - -インテグレーション環境用の認証済み cloud-init.yaml ファイルを用意し、`cloud-init` config を使用する新しい Confidential VM を作成すれば、GCP VM エンクレーブ内の新しい UID2 Operator Service をインテグレーション環境にデプロイできます。 - -このセクションでは、デプロイメントプロセスについて説明します。 - -### Cloud-init.yaml File - -登録プロセスでは、認証された cloud-init-``.yaml ファイルが提供されます。このファイルの SHA-256sum は認証プロセスの一部として使用されるため、このファイルを (クライアント API キーを追加する以外の)いかなる方法でも変更することはできません。ファイルの内容は後述しますが、このファイルはデプロイプロセス中に手動で作成されることはなく、常に UID チームが新しい Private Operator を設定するプロセス中に作成されます。 - -cloud-init.yaml ファイルは環境に固有なので、インテグレーション環境用と本番環境用を用意することに注意してください。 - -### cloud-init Example - -これは、UID2 Operator エンクレーブをインテグレーション環境にデプロイする際に使用する `cloud-init` テンプレートです。このセクションでは、ファイルの内容について説明しますが、登録時に提供されたものを使用する必要があります。 - -このファイルの内容は、VM インスタンスの作成時に `user-data` というキーでカスタムメタデータとして提供する必要があります。この `user-data` メタデータは、起動時にコンテナ最適化 OS (COS) の VM ディスクによって読み込まれ、解釈されます。 - -以下の例に示すように、まずリモート SSH アクセスを無効にし、次に COS VM に対して、`docker pull`を使って UID2 プロジェクトの公式コンテナレジストリから認証済みの UID2 Operator Docker イメージを Pull し、UID2 Operator コンテナを `systemd` サービスとして実行させるように指示します。 - -提供されたファイルでは、`UID2_ENCLAVE_IMAGE_ID` と `GHCR_RO_ACCESS_TOKEN` の値は既に設定されています。手動で編集する必要はありません。`UID2_ENCLAVE_API_TOKEN` は別途提供されますので、ファイル内のこの値を更新する必要があります。 - -``` -#cloud-config - -bootcmd: -- iptables -D INPUT -p tcp -m tcp --dport 22 -j ACCEPT -- iptables -A INPUT -p tcp -m tcp --dport 22 -j DROP -- systemctl mask --now serial-getty@ttyS0.service - -runcmd: -- systemctl daemon-reload -- systemctl start uid2-operator.service - -write_files: -- path: /etc/systemd/system/uid2-operator.service - permissions: 0644 - owner: root - content: | - [Unit] - Description=Start UID 2.0 operator as a Docker container - - [Service] - Environment="UID2_ENCLAVE_API_TOKEN=" - Environment="UID2_ENCLAVE_IMAGE_ID=" - Environment="GHCR_RO_ACCESS_TOKEN=" - Environment="HOME=/run/uid2" - ExecStartPre=mkdir -p /run/uid2/.config/gcloud - ExecStartPre=docker login ghcr.io -u gcp-uid2-docker -p ${GHCR_RO_ACCESS_TOKEN} - ExecStartPre=/usr/bin/docker-credential-gcr configure-docker - ExecStart=/usr/bin/docker run --rm --name uid2-operator -v /run/uid2/operator.json:/app/conf/config.json -e KUBERNETES_SERVICE_HOST=1 -e core_api_token=${UID2_ENCLAVE_API_TOKEN} -e optout_api_token=${UID2_ENCLAVE_API_TOKEN} -p 80:8080 ghcr.io/iabtechlab/uid2-operator@SHA-256:${UID2_ENCLAVE_IMAGE_ID} - ExecStop=/usr/bin/docker stop uid2-operator - ExecStopPost=/usr/bin/docker rm uid2-operator -- path: /run/uid2/operator.json - permissions: 0644 - owner: root - content: | - { - "clients_metadata_path": "https://core-integ.uidapi.com/clients/refresh", - "keys_metadata_path": "https://core-integ.uidapi.com/key/refresh", - "keys_acl_metadata_path": "https://core-integ.uidapi.com/key/acl/refresh", - "salts_metadata_path": "https://core-integ.uidapi.com/salt/refresh", - "core_attest_url": "https://core-integ.uidapi.com/attest", - "optout_metadata_path": "https://optout-integ.uidapi.com/optout/refresh", - "optout_api_uri": "https://optout-integ.uidapi.com/optout/replicate", - "optout_s3_folder": "optout-v2/", - "optout_inmem_cache": true, - "identity_token_expires_after_seconds": 14400, - "refresh_token_expires_after_seconds": 2592000, - "refresh_identity_token_after_seconds": 3600, - "enclave_platform": "gcp-vmid", - "enforce_https": true, - "service_instances": 16, - "allow_legacy_api": false - } -``` - -### Create VM Instance - -新しい VM インスタンスを作成するには、登録時に渡されたファイルを使って以下の手順を実行します。 - -1. cloud-init-``.yaml ファイルを一時的な場所にコピーしてください。 -2. 同じフォルダーにある [gcloud script](https://cloud.google.com/blog/products/management-tools/scripting-with-gcloud-a-beginners-guide-to-automating-gcp-tasks) ファイルを実行します。 - これにより、正しい VM イメージと `cloud-init` ファイルを使用した新しい GCP Confidential VM が作成されます。 - -`gcloud` スクリプトファイルの例は以下のとおりです: - -``` -$ gcloud compute instances \ - create uid2-operator-gcp-01 \ - --confidential-compute \ - --maintenance-policy Terminate \ - --image https://www.googleapis.com/compute/v1/projects/cos-cloud/global/images/cos-stable-101-17162-40-56 \ - --metadata-from-file user-data=./cloud-init-1674598899.yaml \ - --tags http-server -``` - -VM の名前 (上の例では uid2-operator-gcp-01)は変更できますが、その他のパラメータは変更できず、認証に失敗します。 - -## Production Deployment - -インテグレーション環境と同じ手順で、GCP VM エンクレーブの新しい UID2 Operator を本番環境にデプロイできます。 -cloud-init-``.yaml ファイルの新しいインスタンスが必要です。このファイルには、UID2 Core Service の本番用 URL が使用します。また、新しい `gcloud` スクリプトファイルも提供されます。インテグレーション環境用のスクリプトファイルと本番環境用のスクリプトファイルには、2 箇所の違いしかありません: - -- 使用する cloud-init-``.yaml ファイル名。 -- `machine-type` の設定。本番環境では、`gcloud` スクリプトでマシンタイプを指定することが推奨されます。現在、UID2 オペレーターは `n2d-standard-16` のマシンタイプで実行することが推奨されています。 - -以下は、スクリプトの例です。 - -``` -$ gcloud compute instances \ - create uid2-operator-gcp-01 \ - --machine-type n2d-standard-16 \ - --confidential-compute \ - --maintenance-policy Terminate \ - --image https://www.googleapis.com/compute/v1/projects/cos-cloud/global/images/cos-stable-101-17162-40-56 \ - --metadata-from-file user-data=./cloud-init-1674598899.yaml \ - --tags http-server -``` - -> NOTE: 前のセクションで使用した `gcloud` コマンドと比較して、 `--machine-type n2d-standard-16` という追加のオプションが追加されています。このオプションは、UID2 Operator Service の本番環境での実行を保証するものです。 -> このオプションは、UID2 Operator Service の本番環境でのデプロイが、本番環境と一致する推奨のマシンタイプで実行されることを保証します。 - -## Upgrading - -各オペレーターのバージョンを更新するために、Private operator は、古いバージョンが非アクティブになり、サポートされなくなるときに、アップグレードのウィンドウを持つメール通知を受け取ります。 -最新バージョンにアップグレードするには、元のオペレーターをデプロイしたのと同じ方法で、メールで提供される新しい `cloud-init` 設定をデプロイします。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-private-gcp-confidential-space.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-private-gcp-confidential-space.md new file mode 100644 index 000000000..5990d5f1a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/operator-private-gcp-confidential-space.md @@ -0,0 +1,486 @@ +--- +title: UID2 Operator - Google Cloud Platform Confidential Space +sidebar_label: GCP Confidential Space +pagination_label: UID2 Operator - Google Cloud Platform Confidential Space +description: Integration information for Private Operator in GCP. +hide_table_of_contents: false +sidebar_position: 18 +--- + +# UID2 Private Operator—Google Cloud Platform Confidential Space + +This guide provides information for setting up the UID2 Operator Service in [Confidential Space](https://cloud.google.com/confidential-computing#confidential-space), a confidential computing option from [Google Cloud](https://cloud.google.com/docs/overview/) Platform. Confidential Space offers a secure enclave environment, known as a Trusted Execution Environment (TEE). + +>NOTE: The UID2 Private Operator implementation for GCP Confidential Space is not supported in these areas: Europe, China. + +The Operator Service runs in a Confidential Space "workload"—a containerized Docker image that runs in a secure cloud-based enclave on top of the Confidential Space image. + +When the Docker container for the UID2 Operator Confidential Space starts up, it completes the attestation process that allows the UID2 Core Service to verify the authenticity of the Operator Service and the enclave environment that the Operator Service is running in. + +When the attestation is successful, the UID2 Core Service provides seed information such as salts and keys to bootstrap the UID2 Operator in the secure Confidential Space container. + +## Setup Overview + +At a high level, the setup steps are as follows: + +1. Create your Confidential Space and UID2 Operator accounts and get, or create, the various values that you'll need for configuration and deployment: see [Prerequisites](#prerequisites). +1. Review information about [deployment environments](#deployment-environments). + + Best practice is to deploy in the integration environment first, and then the production environment. +1. Review information about the [deployment options](#deployment-options) available, including the benefits of each, and decide which to use. + + We recommend the Terraform template option. +1. Follow the applicable instructions for the deployment option you chose, out of the following: + - [Terraform Template](#deployterraform-template) + - [gcloud CLI](#deploygcloud-cli) + +When all steps are complete, your implementation should be up and running. + +## Prerequisites + +Before setting up your UID2 Operator Service in the Google Cloud Platform using Confidential Space, complete these prerequisite steps: + +- [Confidential Space Account Setup](#confidential-space-account-setup) +- [UID2 Operator Account Setup](#uid2-operator-account-setup) + +### Confidential Space Account Setup + +You can run the UID2 Operator Service on any GCP account and project. However, to support attestation, you'll need to create a service account that you can use to run Confidential Space virtual machines (VMs). + +Before choosing your deployment option, complete these Google Cloud setup steps: + +1. Create the GCP project that you want the UID2 Operator to run in. We recommend creating a new project for the UID2 Operator Service, but you could also use an existing one. Follow these guidelines: + + - Choose a project name; for example, `UID2-Operator-Production`. You'll use this as the `{PROJECT_ID}` value in later steps. + - Make sure that you define a GCP project with billing enabled. + +1. Choose a name for the GCP service account that you'll use to run Confidential Space VMs; for example, `uid2-operator`. You'll use this as the `{SERVICE_ACCOUNT_NAME}` value in later steps. + +1. Install the gcloud CLI, required by both deployment options. Follow the instructions provided by Google: [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install). + +### UID2 Operator Account Setup +Ask your UID2 contact to register your organization as a UID2 Operator. If you're not sure who to ask, see [Contact Info](../getting-started/gs-account-setup.md#contact-info). + +>TIP: It's a good idea to set up an internal email distribution list of individuals who should be kept informed about new versions and any other technical notifications or requests, and provide that as the email contact. + +When the registration process is complete, you'll receive the following: + +| Item | Description | +| :--- | :--- | +| `{OPERATOR_IMAGE}` | The Docker image URL for the UID2 Private Operator for GCP, used in configuration. The following example is fictitious, but shows what the Docker image URL might look like: `https://console.cloud.google.com/artifacts/docker/uid2-prod-project/us/iabtechlab/uid2-operator/sha256:2e4fae98b688002303c6263f7c4bf95344a1d9c15fb5fcf838b59032bb9813f2`. Use the image URL provided to you as part of account setup.
NOTE: The image is valid for both deployment environments. | +| `{OPERATOR_KEY}` | An operator key, exclusive to you, that identifies you with the UID2 service as a private operator. Use this as the `OPERATOR_KEY` value during configuration. This value is both your unique identifier and a password; store it securely and do not share it.
NOTE: You'll receive a separate operator key for each deployment environment. | +| Instructions | Additional information details, such as instructions for setting up VMs or a link to the applicable information. | + +When UID2 account registration is complete, and you've installed the gcloud CLI, your next steps are: +- Review information about [deployment environments](#deployment-environments). +- Review information about the [deployment options](#deployment-options) available, including the benefits of each, and decide which to use. + +## Deployment Environments + +The following environments are available, and both [deployment options](#deployment-options) support both environments. + +As a best practice, we recommend that you test and verify your implementation in the integration environment before deploying in the production environment. + +>NOTE: You'll receive separate `{OPERATOR_KEY}` values for each environment. Be sure to use the correct one. The `{OPERATOR_IMAGE}` value is the same for both environments. + +| Environment | Details | +| :--- | :--- | +| Integration (`integ`) | For testing only. Debug mode is available in the integration environment. | +| Production (`prod`) | For managing production traffic. For this environment, we recommend deploying via the Terraform template, with load balancing, and with HTTPS enabled. See [Deployment Options](#deployment-options). | + +## Deployment Options + +There are two deployment options: + +| Option | Details | +| :--- | :--- | +| [Terraform template](#deployterraform-template) | This option:
  • Does not require manually setting up a service account. The setup is very simple.
  • Brings up a whole stack with a load balancer and a scaling group.
  • Is easier to maintain and operate than the `gcloud` option.
  • Is very simple to upgrade.
  • Is the recommended deployment solution.
| +| [gcloud CLI](#deploygcloud-cli) | This option:
  • Brings up one VM instance with a public IP address.
  • Can be easier for quick experimentation/evaluation.
  • For multiple instances, requires bringing up each instance manually, by running the command multiple times.
  • Requires setting up the load balancer manually.
  • Is more complex to upgrade, since more manual steps are needed.
| + +Both deployment options support both deployment environments. + +To determine your next steps, choose the deployment option you want to use. Then, follow the applicable instructions: +- [Deploy—Terraform Template](#deployterraform-template) +- [Deploy—gcloud CLI](#deploygcloud-cli) + +### Deploy—Terraform Template + +For ease of deployment and upgrade, you can use a Terraform template to deploy a UID2 Private Operator implementation with load balancing and auto-scaling features. In this scenario, all VM instances run on Confidential Space VMs, and are deployed in multiple availability zones (AZs). + +The Terraform template does the following: +- Activates the required Google Cloud Platform APIs. +- Sets up a service account to run Confidential Space VMs. +- Creates a secret to hold the `operator_key` value. +- Creates the following components: + - Network: VPC and subnetwork. + - Instances: Instance template, instance groups (with auto-scaling enabled). + - Ingress: Load balancer (with health check), forwarding rules, and firewall rules. + - Egress: [Cloud Network Address Translation (NAT)](https://cloud.google.com/nat/docs/overview). +- If HTTPS is enabled, provides your HTTPS certificate to Terraform. + +>NOTE: The Terraform template uses the gcloud CLI that you installed in [Confidential Space Account Setup](#confidential-space-account-setup) Step 3. + +To deploy a new UID2 Operator in the GCP Confidential Space Enclave, using the Terraform template, follow these steps: + +1. [Install Terraform](#install-terraform) +1. [Set Up the Terraform Environment](#set-up-the-terraform-environment) +1. [Download the Template Files](#download-the-template-files) +1. [Provide Input Values](#provide-input-values) +1. [Run Terraform](#run-terraform) +1. [Test Terraform Using the Health Check Endpoint](#test-terraform-using-the-health-check-endpoint) + +For additional information, see: +- [Delete All Created Resources](#delete-all-created-resources) +- [Outputs](#outputs) + +#### Install Terraform + +Install Terraform if it is not already installed: visit [terraform.io](https://www.terraform.io/). + +#### Set Up the Terraform Environment + +1. Create a new project or select an existing one, replacing the `{PROJECT_ID}` placeholder with your own project ID (see [Confidential Space Account Setup](#confidential-space-account-setup)): + + ``` + gcloud config set project {PROJECT_ID} + ``` + +2. Configure the environment for Terraform: + + ``` + gcloud auth application-default login + ``` + +#### Download the Template Files + +Follow the instructions you receive when your registration process is complete (see [UID2 Operator Account Setup](#uid2-operator-account-setup)) to download the template files listed in the following table. + +| File | Details | +| :--- | :--- | +| `main.tf` | The Terraform template file. | +| `variables.tf` | Contains the definitions for the template input variables, including name, type, and default value. | +| `outputs.tf` | Includes output definitions. | +| `terraform.tfvars` | Contains the values for the template input variables. | + +#### Provide Input Values + +Provide values for the input parameters, as needed, in the `terraform.tfvars` file that you downloaded. Some are required, others are optional. + +1. Provide values for the required input parameters shown in the following table: + + | Name | Type | Default | Required | Description | + | :--- | :--- | :--- | :--- | :--- | + | `project_id` | `string` | n/a | yes | The ID of the GCP project that you want the UID2 Operator to run in; for example, `UID2-Operator-Production`. | + | `service_account_name` | `string` | n/a | yes | The name of the service account that you want to use for your UID2 Operator instance in GCP Confidential Space. | + | `uid_operator_image` | `string` | n/a | yes | The Docker image URL for the UID2 Private Operator for GCP, used in configuration, which you received as part of [UID2 Operator Account Setup](#uid2-operator-account-setup). For example: `us-docker.pkg.dev/uid2-prod-project/iabtechlab/uid2-operator@sha256:{IMAGE_SHA}`. | + | `uid_operator_key` | `string` | n/a | yes | The UID2 operator key, which you received as part of [UID2 Operator Account Setup](#uid2-operator-account-setup). | + | `uid_deployment_env` | `string` | `integ` | yes | Valid values: `integ` for integration environment, `prod` for production environment.
Machine type is determined by the deployment environment: `integ` uses `n2d-standard-2` and `prod` uses `n2d-standard-16`. | + +1. (Optional, strongly recommended) Set the load balancer to HTTPS. Provide values for the parameters shown in the following table: + + | Name | Type | Default | Required | Description | + | :--- | :--- | :--- | :--- | :--- | + | `ssl` | `bool` | `false`| no | To set the load balancer to use HTTPS, which is recommended, set this flag to `true`.
If you're using HTTPS you must also specify values for the `certificate` and `private_key` parameters. | + | `certificate` | `string` | n/a | no | The contents of the HTTPS certificate. The certificate should be in PEM format.
For example: `file('path/to/certificate.pem')`.
Required if `ssl` is set to `true`.
For details, see [google_compute_ssl_certificate](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_ssl_certificate#certificate) in the Terraform documentation. | + | `private_key` | `string` | n/a | no | The contents of the private key for the HTTPS certificate. The private key should be in PEM format.
For example: `file('path/to/private_key.pem')`.
Required if `ssl` is set to `true`.
For details, see [google_compute_ssl_certificate](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_ssl_certificate#private_key) in the Terraform documentation. | + +1. (Optional) Provide parameter names and values for the additional input parameters shown in the following table. These parameters are always optional, but you might want to modify from the default values to better suit your requirements. + + | Name | Type | Default | Required | Description | + | :--- | :--- | :--- | :--- | :--- | + | `region` | `string` | `us-east1` | no | The region that you want to deploy to. For a list of valid regions, see [Available regions and zones](https://cloud.google.com/compute/docs/regions-zones#available) in the Google Cloud documentation.
NOTE: The UID2 Private Operator implementation for GCP Confidential Space is not supported in these areas: Europe, China. | + | `network_name` | `string` | `uid-operator` | no | The VPC resource name (also used for rules/ instance tags). | + | `min_replicas` | `number` | `1` | no | Indicates the minimum number of replicas you want to deploy. | + | `max_replicas` | `number` | `5` | no | Indicates the maximum number of replicas you want to deploy. | + | `uid_operator_key_secret_name` | `string` | `"secret-operator-key"` | no | The name that you specify for your operator key secret. The Terraform template creates a secret in the GCP Secret Manager to hold the `uid_operator_key` value. You can define the name; for example, `uid2-operator-operator-key-secret-integ`. | + | `debug_mode` | `bool` | `false` | no | Do not set to `true` unless you are working with the UID2 team to debug an issue. In any other circumstances, if you set this flag to `true`, attestation will fail. | + +#### Run Terraform + +Run the following: + +``` +terraform init +terraform apply +``` +When you run `terraform apply`, the following file is generated in the same folder: [`terraform.tfstate`](https://developer.hashicorp.com/terraform/language/state). This file stores state information about your managed infrastructure and configuration. + +This file will be used for future maintenance. Be sure to persist it remotely. + +#### Test Terraform Using the Health Check Endpoint + +Call the health check endpoint to test the health of your implementation. The expected result is HTTP 200 with a response body of `OK`. + +For instructions, see [Health Check—Terraform Template](#health-checkterraform-template). + +#### Delete All Created Resources + +In a scenario where you want to clean up, you can remove the resources created by the template. For example, you might want to test `integ` and remove the whole stack later. + +To remove all resources created by Terraform, run the following: + +``` +terraform destroy +``` + +#### Outputs + +The following table summarizes the output value from the Terraform template. + +| Name | Description | +| :--- | :--- | +| `load_balancer_ip` | The public IP address of the load balancer.
You can use this value to [perform the health check](#health-checkterraform-template) or to configure the DNS. | + +### Deploy—gcloud CLI + +To deploy a new UID2 Operator in the GCP Confidential Space Enclave using the gcloud CLI, follow these steps. + +>NOTE: For deployment to the production environment we do not recommend this option. We recommend deploying via the Terraform template, with load balancing, and with HTTPS enabled. + + 1. [Set Up Service Account Rules and Permissions](#set-up-service-account-rules-and-permissions) + 1. [Create Secret for the Operator Key in Secret Manager](#create-secret-for-the-operator-key-in-secret-manager) + 1. [Update the Script with Valid Values](#update-the-script-with-valid-values) + 1. [Run the Script](#run-the-script) + 1. [Test gcloud Using the Health Check Endpoint](#test-gcloud-using-the-health-check-endpoint) + +#### Set Up Service Account Rules and Permissions + +To set up and configure the account that you created when you installed the gcloud CLI, complete the following steps. Replace the placeholder values with your own valid values. + +1. Switch to the project that you created in [Confidential Space Account Setup](#confidential-space-account-setup): + ``` + $ gcloud config set project {PROJECT_ID} + ``` + +1. Enable the following APIs: + + | Name | Description | + | :--- | :--- | + | compute.googleapis.com | Compute Engine API | + | confidentialcomputing.googleapis.com | Confidential Computing API | + | logging.googleapis.com | Cloud Logging API | + | secretmanager.googleapis.com | Service Management API | + + Run this command to enable the APIs: + + ``` + $ gcloud services enable compute.googleapis.com \ + confidentialcomputing.googleapis.com \ + logging.googleapis.com \ + secretmanager.googleapis.com + ``` + +1. Create a service account to run the UID2 Operator Service: + ``` + $ gcloud iam service-accounts create {SERVICE_ACCOUNT_NAME} + ``` + +1. Grant the required permissions to the service account. + + Permissions are shown in the following table. + + | Permission | Description | + | :--- | :--- | + | `confidentialcomputing.workloadUser` | Provides the permission to generate an attestation token and run a workload in a VM. | + | `logging.logWriter` | Provides the permission to write log entries in gcloud logging. | + | `secretmanager.secretAccessor` | Provides the permission to access the operator key that is managed in the GCP Secret Manager. | + + Grant the `confidentialcomputing.workloadUser` permission: + + ``` + $ gcloud projects add-iam-policy-binding {PROJECT_ID} \ + --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ + --role=roles/confidentialcomputing.workloadUser + ``` + Grant the `logging.logWriter` permission: + + ``` + $ gcloud projects add-iam-policy-binding {PROJECT_ID} \ + --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ + --role=roles/logging.logWriter + ``` + + Grant the `secretmanager.secretAccessor` permission: + + ``` + $ gcloud projects add-iam-policy-binding {PROJECT_ID} \ + --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ + --role=roles/secretmanager.secretAccessor + ``` + +1. Add a VPC rule to allow public access on port 8080, the default exposed port for the UID2 operator: + ``` + $ gcloud compute firewall-rules create operator-tcp \ + --direction=INGRESS --priority=1000 --network=default --action=ALLOW \ + --rules=tcp:8080 \ + --source-ranges=0.0.0.0/0 \ + --target-service-accounts={SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com + ``` + +#### Create Secret for the Operator Key in Secret Manager + +As part of setting up your UID2 account (see [UID2 Operator Account Setup](#uid2-operator-account-setup)), you'll receive an operator key for each environment. + +The next step is to store the `{OPERATOR_KEY}` value in GCP Secret Manager and get a full secret name for it, which you later use to replace the `{OPERATOR_KEY_SECRET_FULL_NAME}` placeholder in the deployment script (see [Update the Script with Valid Values](#update-the-script-with-valid-values)). + +Follow these steps: + 1. Run the following script, which creates a new secret, first customizing with your own values: + + ``` + OPERATOR_KEY="{OPERATOR_KEY}" + echo -n $OPERATOR_KEY | gcloud secrets create {OPERATOR_KEY_SECRET_NAME} \ + --replication-policy="automatic" \ + --data-file=- + ``` + + 1. Prepare the script, using your own values: + + - For `{OPERATOR_KEY}`, use your own operator key value for the environment. + - For `{OPERATOR_KEY_SECRET_NAME}`, specify the name you want to use for your API secret, for this environment. For example: `uid2-operator-operator-key-secret-integ`. + + 2. Run the script. + + The script creates the secret in GCP Secret Manager. The secret (display) name is {OPERATOR_KEY_SECRET_NAME} and the secret value is {OPERATOR_KEY}. + +1. Run the following command to get the full secret name, including the path, first customizing with your own values: + + ``` + $ gcloud secrets versions describe latest --secret {OPERATOR_KEY_SECRET_NAME} --format 'value(name)' + ``` + +In this example, the full secret name might be: `projects/111111111111/secrets/uid2-operator-operator-key-secret-integ/versions/1`. This is the value that you would use to replace the `{OPERATOR_KEY_SECRET_FULL_NAME}` placeholder in the next section. + +#### Update the Script with Valid Values + +Update the example script, using your own valid values instead of the placeholder values. + +This section includes: + +- [Placeholder Values and Definitions](#placeholder-values-and-definitions) +- [Sample Deployment Script—Integ](#sample-deployment-scriptinteg) +- [Sample Deployment Script—Prod](#sample-deployment-scriptprod) + +##### Placeholder Values and Definitions + +Placeholder values are defined in the following table. + +| Placeholder | Actual Value | +| :--- | :--- | +| `{INSTANCE_NAME}` | Your own valid VM name. | +| `{ZONE}` | The Google Cloud zone that the VM instance will be deployed on. | +| `{SERVICE_ACCOUNT}` | The service account email that you created as part of creating your account, in this format: `{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com`.
For details, see [Set Up Service Account Rules and Permissions](#set-up-service-account-rules-and-permissions) (Step 4). | +| `{OPERATOR_IMAGE}` | The Docker image URL for the UID2 Private Operator for GCP, used in configuration.
For details, see [UID2 Operator Account Setup](#uid2-operator-account-setup). | +| `{OPERATOR_KEY_SECRET_FULL_NAME}` | The full name that you specified for the Operator Key secret (see [Create Secret for the Operator Key in Secret Manager](#create-secret-for-the-operator-key-in-secret-manager)), including the path, in the format `projects//secrets//versions/`. For example: `projects/111111111111/secrets/uid2-operator-operator-key-secret-integ/versions/1`. | + +##### Sample Deployment Script—Integ + +The following example of the deployment script for the integration environment uses some placeholder values. + +``` +$ gcloud compute instances create {INSTANCE_NAME} \ + --zone {ZONE} \ + --machine-type n2d-standard-2 \ + --confidential-compute \ + --shielded-secure-boot \ + --maintenance-policy Terminate \ + --scopes cloud-platform \ + --image-project confidential-space-images \ + --image-family confidential-space \ + --service-account {SERVICE_ACCOUNT} \ + --metadata ^~^tee-image-reference={OPERATOR_IMAGE}~tee-restart-policy=Never~tee-env-DEPLOYMENT_ENVIRONMENT=integ~tee-env-API_TOKEN_SECRET_NAME={OPERATOR_KEY_SECRET_FULL_NAME} +``` + +##### Sample Deployment Script—Prod + +The following example of the deployment script for the production environment uses some placeholder values. + +>NOTE: A `machine-type` value of `n2d-standard-16` is required for the production environment. + +``` +$ gcloud compute instances create {INSTANCE_NAME} \ + --zone {ZONE} \ + --machine-type n2d-standard-16 \ + --confidential-compute \ + --shielded-secure-boot \ + --maintenance-policy Terminate \ + --scopes cloud-platform \ + --image-project confidential-space-images \ + --image-family confidential-space \ + --service-account {SERVICE_ACCOUNT} \ + --metadata ^~^tee-image-reference={OPERATOR_IMAGE}~tee-restart-policy=Never~tee-env-DEPLOYMENT_ENVIRONMENT=prod~tee-env-API_TOKEN_SECRET_NAME={OPERATOR_KEY_SECRET_NAME} +``` + +#### Run the Script + +When the script is ready, with the additional valid values, run it. + +#### Test gcloud Using the Health Check Endpoint + +Call the health check endpoint to test the health of your implementation. The expected result is HTTP 200 with a response body of `OK`. + +For instructions, see [Health Check—gcloud CLI](#health-checkgcloud-cli). + +## Tasks + +This section provides instructions for completing the following tasks. Where applicable, instructions are provided for both environments. It includes: + +- [Running the Health Check](#running-the-health-check) +- [Upgrading](#upgrading) + +### Running the Health Check + +Call the health check endpoint to test the health of your implementation. + +Running the health check is the same for the integration and production environments, except for the endpoints. + +Follow the applicable instructions depending on the deployment option you chose: + +- [Health Check—Terraform Template](#health-checkterraform-template) +- [Health Check—gcloud CLI](#health-checkgcloud-cli) + +#### Health Check—Terraform Template + +The following example shows the health check for the Terraform template option: + +1. Get the public IP address for the load balancer: + + ``` + terraform output load_balancer_ip + ``` + +2. To test operator status, in your browser, go to the health check endpoint: `http://{IP}/ops/healthcheck`. + + An HTTP 200 with a response body of `OK` indicates healthy status. + + +#### Health Check—gcloud CLI +The following example shows the health check for the `gcloud` command line option: + +1. Get the public IP address of the deployed instance: + + ``` + $ gcloud compute instances describe {INSTANCE_NAME} \ + --format='get(networkInterfaces[0].accessConfigs[0].natIP)' + ``` +2. To test operator status, in your browser, go to `http://{IP}:8080/ops/healthcheck`. + + An HTTP 200 with a response body of `OK` indicates healthy status. + +### Upgrading + +When a new version of UID2 Google Cloud Platform Confidential Space is released, private operators receive an email notification of the update, with a new image version. There is a window of time for upgrade, after which the older version is deactivated and is no longer supported. + +If you're upgrading to a new version, the upgrade process depends on the deployment option you chose. Follow the applicable steps: + +- [Upgrading—Terraform Template](#upgradingterraform-template) +- [Upgrading—gcloud CLI](#upgradinggcloud-cli) + +#### Upgrading—Terraform Template + +If you deployed using the Terraform template, all you need to do to upgrade is update your deployment with the new `{OPERATOR_IMAGE}` that you received in the upgrade notification. + +#### Upgrading—gcloud CLI + +If you deployed using the gcloud CLI, you must manually bring up new instances that use the new `{OPERATOR_IMAGE}` and then shut down old instances. + +If you previously set up a load balancer manually, you'll also need to update the mapping for the load balancer. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md index 94194ddcd..2aa69f7b1 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md @@ -1,5 +1,7 @@ --- title: UID2 Integration Guides - Summary +sidebar_label: Summary +pagination_label: UID2 Integration Guides - Summary description: 利用可能なすべてのインテグレーションガイドの概要。 hide_table_of_contents: false sidebar_position: 01 @@ -44,4 +46,4 @@ sidebar_position: 01 | :----------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [UID2 Operator - Microsoft Azure Confidential Compute Operator Package](./operator-guide-azure-enclave.md) | IMPORTANT: このドキュメントは現在、PoC の段階です。詳細は、UID2 Administrator に [連絡](../getting-started/gs-account-setup.md#contact-info) してください。
Closed Operator Service を Microsoft Azure Confidential Computing プラットフォーム上で動作させるためのセットアップ手順です。 | | [UID2 Operator - AWS Marketplace](./operator-guide-aws-marketplace.md) | AWS Marketplace のクローズドオペレーターサービスをセットアップする手順です。　 | -| [UID2 Operator - Google Cloud Platform Confidential Compute package](./operator-guide-gcp-enclave.md) | Google Cloud Platform Confidential Compute (GCP) パッケージのセットアップ手順です。 | + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-operators-private.md b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-operators-private.md index 7fe13c225..c1420f1d1 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-operators-private.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-operators-private.md @@ -40,7 +40,7 @@ Private Operator が UID2 を実装するために、以下のドキュメント | Integration Type| Documentation | Content Description | Audience | | :--- | :--- | :--- | :--- | | Operator | [UID2 Operator - AWS Marketplace Integration Guide](../guides/operator-guide-aws-marketplace.md) | AWS MarketplaceのPrivate Operator Service を設定する手順です。 | Private Operators
Publishers | -| GCP| [UID2 Operator - Google Cloud Platform Confidential Computing package](../guides/operator-guide-gcp-enclave.md) | Google Cloud Platform Confidential Computing パッケージ (GCP)を設定する手順です。 | Private Operators
Publishers | + | Azure | [Operator - Microsoft Azure](../guides/operator-guide-azure-enclave.md) | IMPORTANT: このドキュメントは現在、PoCの段階です。
Microsoft Azure Confidential Computingプラットフォーム上で実行するPrivate Operator Service のセットアップ手順です。 | Private Operators
Publishers | ## Getting Started diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-publishers.md b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-publishers.md index f02a0f27a..d9a5d1f7b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-publishers.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-publishers.md @@ -73,7 +73,7 @@ UID2 とインテグレーションすることで得られるメリットの一 | Integration Type| Documentation | Content Description | Audience | | :--- | :--- | :--- | :--- | | Operator | [UID2 Operator - AWS Marketplace Integration Guide](../guides/operator-guide-aws-marketplace.md) | AWS Marketplace の Private Operator Service を設定する手順です。 | Private Operators
Publishers | -| Operator| [UID2 Operator - Google Cloud Platform Confidential Computing package](../guides/operator-guide-gcp-enclave.md) | Google Cloud Platform Confidential Computing パッケージ (GCP)のセットアップ手順です。 | Private Operators
Publishers | + | Operator Integration Guide | [Operator - Microsoft Azure](../guides/operator-guide-azure-enclave.md) | IMPORTANT: このドキュメントは現在、PoC の段階です。UID2 Administrator に [連絡](../getting-started/gs-account-setup.md#contact-info) してください。
Microsoft Azure Confidential Computing platform 上で実行する Private Operator Service のセットアップ手順です。 | Private Operators
Publishers | ## Workflow for Publishers diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md index 14621574e..aa456cc1a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md @@ -148,7 +148,7 @@ sidebar_position: 10
Enclave は、コンピューティング環境のセキュアなサブセクションです。エンクレーブには追加のビジネスロジックとセキュリティ対策が施され、改ざんできないようになっています。
UID2 のコンテキストでは、 private operator は、Enclave 内かプライベート環境で運用しなければなりません。must run inside an enclave or in a private environment. サポートされるエングレーブのバージョンは次のとおりです:
- AWS Nitro: UID2 Operator - AWS Marketplace Integration Guide を参照してください。
-- Google Cloud Platform Confidential Computing: UID2 Operator - Google Cloud Platform Confidential Computing Package を参照してください。
+- Google Cloud Platform Confidential Computing。
- Microsoft Azure confidential computing: Microsoft Azure Confidential Compute Operator Package を参照してください。
エンクレーブでは、オペレータ・イメージは非常に特殊で、事前に定義されたバージョンでなければならず、セキュリティを確保するために追加の制約が適用されます。
@@ -168,8 +168,6 @@ UID2 のコンテキストでは、「ID」という用語は、UID2 Token、Ref
JSON Web Token (JWT)
JSON Web Token (JWT) は、Web 上で一方の当事者から別の当事者に送信されるクレーム (情報) を表す、コンパクトで URL セーフな手段です。JWT 内のクレームは、JSON Web Signature (JWS) 構造のペイロードまたは JSON Web Encryption (JWE) 構造のプレーン テキストとして使用される JSON オブジェクトとしてエンコードされます。これにより、クレームにデジタル署名や暗号化を行うことができます。
-
UID2 は、Google Cloud Platform (GCP) Enclave とのインターフェースの一部として JSON Web Token を使用します。
-
詳細は、UID2 Operator - Google Cloud Platform Confidential Compute package を参照してください。
Normalize
データセットを Normalize (正規化)するとは、それを標準的な状態 (Condition)や状態 (State)にすることを意味します。
diff --git a/package-lock.json b/package-lock.json index 20c87c683..a5f93ae8d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4827,9 +4827,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001470", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001470.tgz", - "integrity": "sha512-065uNwY6QtHCBOExzbV6m236DDhYCCtPmQUCoQtwkVqzud8v5QPidoMr6CoMkC2nfp6nksjttqWQRRh75LqUmA==", + "version": "1.0.30001540", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001540.tgz", + "integrity": "sha512-9JL38jscuTJBTcuETxm8QLsFr/F6v0CYYTEU6r5+qSM98P2Q0Hmu0eG1dTG5GBUmywU3UlcVOUSIJYY47rdFSw==", "funding": [ { "type": "opencollective", @@ -4838,6 +4838,10 @@ { "type": "tidelift", "url": "https://tidelift.com/funding/github/npm/caniuse-lite" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" } ] }, diff --git a/sidebars.js b/sidebars.js index b8a8ebd0c..2cf225849 100644 --- a/sidebars.js +++ b/sidebars.js @@ -130,7 +130,7 @@ const sidebars = { collapsed: true, items: [ 'guides/operator-guide-aws-marketplace', - 'guides/operator-guide-gcp-enclave', + 'guides/operator-private-gcp-confidential-space', 'guides/operator-guide-azure-enclave', ], },