From 04b2105204c9549019af484f23e2856a85d65260 Mon Sep 17 00:00:00 2001 From: sanopsmx Date: Tue, 17 Sep 2024 18:29:46 +0530 Subject: [PATCH] feat(provider/google): Added cloudrun provider reference documentation in spinnaker.io --- content/en/docs/reference/halyard/commands.md | 246 ++++++++++++++++++ .../en/docs/reference/providers/cloudrun.md | 102 ++++++++ .../docs/setup/install/providers/cloudrun.md | 153 +++++++++++ 3 files changed, 501 insertions(+) create mode 100644 content/en/docs/reference/providers/cloudrun.md create mode 100644 content/en/docs/setup/install/providers/cloudrun.md diff --git a/content/en/docs/reference/halyard/commands.md b/content/en/docs/reference/halyard/commands.md index e09a1a50..6eaca9c8 100644 --- a/content/en/docs/reference/halyard/commands.md +++ b/content/en/docs/reference/halyard/commands.md @@ -416,6 +416,16 @@ Published: 2020-04-30 21:10:29 - [hal config provider cloudfoundry account list](#hal-config-provider-cloudfoundry-account-list) - [hal config provider cloudfoundry disable](#hal-config-provider-cloudfoundry-disable) - [hal config provider cloudfoundry enable](#hal-config-provider-cloudfoundry-enable) +- [hal config provider cloudrun](#hal-config-provider-cloudrun) +- [hal config provider cloudrun account](#hal-config-provider-cloudrun-account) +- [hal config provider cloudrun account add](#hal-config-provider-cloudrun-account-add) +- [hal config provider cloudrun account delete](#hal-config-provider-cloudrun-account-delete) +- [hal config provider cloudrun account edit](#hal-config-provider-cloudrun-account-edit) +- [hal config provider cloudrun account get](#hal-config-provider-cloudrun-account-get) +- [hal config provider cloudrun account list](#hal-config-provider-cloudrun-account-list) +- [hal config provider cloudrun disable](#hal-config-provider-cloudrun-disable) +- [hal config provider cloudrun edit](#hal-config-provider-cloudrun-edit) +- [hal config provider cloudrun enable](#hal-config-provider-cloudrun-enable) - [hal config provider dcos](#hal-config-provider-dcos) - [hal config provider dcos account](#hal-config-provider-dcos-account) - [hal config provider dcos account add](#hal-config-provider-dcos-account-add) @@ -9305,6 +9315,242 @@ hal config provider cloudfoundry enable [parameters] --- +## hal config provider cloudrun + +The Cloud Run provider is used to deploy resources to any number of Cloud Run applications. To get started with Cloud Run, visit [https://cloud.google.com/run/docs/](https://cloud.google.com/run/docs/). For more information on how to configure individual accounts, please read the documentation under `hal config provider cloudrun account -h`. + +#### Usage + +``` +hal config provider cloudrun [parameters] [subcommands] +``` + +#### Parameters + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +#### Subcommands + +- `account`: Manage and view Spinnaker configuration for the cloudrun provider's account +- `disable`: Set the cloudrun provider as disabled +- `edit`: Edit Spinnaker's cloud run configuration. +- `enable`: Set the cloudrun provider as enabled + +--- + +## hal config provider cloudrun account + +An account in the Cloud Run provider refers to a single Cloud Run application. Spinnaker assumes that your Cloud Run application already exists. You can create an application in your Google Cloud Platform project by running `gcloud app create --region `. + +#### Usage + +``` +hal config provider cloudrun account ACCOUNT [parameters] [subcommands] +``` + +#### Parameters + +`ACCOUNT`: The name of the account to operate on. + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +#### Subcommands + +- `add`: Add an account to the cloudrun provider. +- `delete`: Delete a specific cloudrun account by name. +- `edit`: Edit an account in the cloudrun provider. +- `get`: Get the specified account details for the cloudrun provider. +- `list`: List the account names for the cloudrun provider. + +--- + +## hal config provider cloudrun account add + +Add an account to the cloudrun provider. + +#### Usage + +``` +hal config provider cloudrun account add ACCOUNT [parameters] +``` + +#### Parameters + +`ACCOUNT`: The name of the account to operate on. + +- `--caching-interval-seconds`: The interval in seconds at which Spinnaker will poll for updates in your CloudRun clusters. +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--environment`: The environment name for the account. Many accounts can share the same environment (e.g. dev, test, prod) +- `--gcloud-release-track`: The gcloud release track (ALPHA, BETA, or STABLE) that Spinnaker will use when deploying to Cloud Run. +- `--json-path`: The path to a JSON service account that Spinnaker will use as credentials. This is only needed if Spinnaker is not deployed on a Google Compute Engine VM, or needs permissions not afforded to the VM it is running on. See [https://cloud.google.com/compute/docs/access/service-accounts](https://cloud.google.com/compute/docs/access/service-accounts) for more information. +- `--local-repository-directory`: (_Default_: `/var/tmp/clouddriver`) A local directory to be used to stage source files for Cloud Run deployments within Spinnaker's Clouddriver microservice. +- `--no-validate`: (_Default_: `false`) Skip validation. +- `--omit-services`: A list of regular expressions. Any service matching one of these regexes will be ignored by Spinnaker. +- `--omit-versions`: A list of regular expressions. Any version matching one of these regexes will be ignored by Spinnaker. +- `--project`: (_Required_) The Google Cloud Platform project this Spinnaker account will manage. +- `--read-permissions`: (_Default_: `[]`) A user must have at least one of these roles in order to view this account's cloud resources. +- `--required-group-membership`: (_Default_: `[]`) A user must be a member of at least one specified group in order to make changes to this account's cloud resources. +- `--services`: A list of regular expressions. Any service matching one of these regexes will be indexed by Spinnaker. +- `--ssh-known-hosts-file-path`: The path to a known_hosts file to be used when connecting with a remote git repository over SSH. +- `--ssh-private-key-file-path`: The path to an SSH private key to be used when connecting with a remote git repository over SSH. +- `--ssh-private-key-passphrase`: (_Sensitive data_ - user will be prompted on standard input) The passphrase to an SSH private key to be used when connecting with a remote git repository over SSH. +- `--ssh-trust-unknown-hosts`: (_Default_: `false`) Enabling this flag will allow Spinnaker to connect with a remote git repository over SSH without verifying the server's IP address against a known_hosts file. +- `--versions`: A list of regular expressions. Any version matching one of these regexes will be indexed by Spinnaker. +- `--write-permissions`: (_Default_: `[]`) A user must have at least one of these roles in order to make changes to this account's cloud resources. + +--- + +## hal config provider cloudrun account delete + +Delete a specific cloudrun account by name. + +#### Usage + +``` +hal config provider cloudrun account delete ACCOUNT [parameters] +``` + +#### Parameters + +`ACCOUNT`: The name of the account to operate on. + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +--- + +## hal config provider cloudrun account edit + +Edit an account in the cloudrun provider. + +#### Usage + +``` +hal config provider cloudrun account edit ACCOUNT [parameters] +``` + +#### Parameters + +`ACCOUNT`: The name of the account to operate on. + +- `--add-read-permission`: Add this permission to the list of read permissions. +- `--add-required-group-membership`: Add this group to the list of required group memberships. +- `--add-write-permission`: Add this permission to the list of write permissions. +- `--caching-interval-seconds`: The interval in seconds at which Spinnaker will poll for updates in your CloudRun clusters. +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--environment`: The environment name for the account. Many accounts can share the same environment (e.g. dev, test, prod) +- `--gcloud-release-track`: The gcloud release track (ALPHA, BETA, or STABLE) that Spinnaker will use when deploying to Cloud Run. +- `--json-path`: The path to a JSON service account that Spinnaker will use as credentials. This is only needed if Spinnaker is not deployed on a Google Compute Engine VM, or needs permissions not afforded to the VM it is running on. See [https://cloud.google.com/compute/docs/access/service-accounts](https://cloud.google.com/compute/docs/access/service-accounts) for more information. +- `--local-repository-directory`: A local directory to be used to stage source files for Cloud Run deployments within Spinnaker's Clouddriver microservice. +- `--no-validate`: (_Default_: `false`) Skip validation. +- `--omit-services`: A list of regular expressions. Any service matching one of these regexes will be ignored by Spinnaker. +- `--omit-versions`: A list of regular expressions. Any version matching one of these regexes will be ignored by Spinnaker. +- `--project`: The Google Cloud Platform project this Spinnaker account will manage. +- `--read-permissions`: A user must have at least one of these roles in order to view this account's cloud resources. +- `--remove-read-permission`: Remove this permission from the list of read permissions. +- `--remove-required-group-membership`: Remove this group from the list of required group memberships. +- `--remove-write-permission`: Remove this permission to from list of write permissions. +- `--required-group-membership`: A user must be a member of at least one specified group in order to make changes to this account's cloud resources. +- `--services`: A list of regular expressions. Any service matching one of these regexes will be indexed by Spinnaker. +- `--ssh-known-hosts-file-path`: The path to a known_hosts file to be used when connecting with a remote git repository over SSH. +- `--ssh-private-key-file-path`: The path to an SSH private key to be used when connecting with a remote git repository over SSH. +- `--ssh-private-key-passphrase`: (_Sensitive data_ - user will be prompted on standard input) The passphrase to an SSH private key to be used when connecting with a remote git repository over SSH. +- `--ssh-trust-unknown-hosts`: Enabling this flag will allow Spinnaker to connect with a remote git repository over SSH without verifying the server's IP address against a known_hosts file. +- `--versions`: A list of regular expressions. Any version matching one of these regexes will be indexed by Spinnaker. +- `--write-permissions`: A user must have at least one of these roles in order to make changes to this account's cloud resources. + +--- + +## hal config provider cloudrun account get + +Get the specified account details for the cloudrun provider. + +#### Usage + +``` +hal config provider cloudrun account get ACCOUNT [parameters] +``` + +#### Parameters + +`ACCOUNT`: The name of the account to operate on. + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +--- + +## hal config provider cloudrun account list + +List the account names for the cloudrun provider. + +#### Usage + +``` +hal config provider cloudrun account list [parameters] +``` + +#### Parameters + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +--- + +## hal config provider cloudrun disable + +Set the cloudrun provider as disabled + +#### Usage + +``` +hal config provider cloudrun disable [parameters] +``` + +#### Parameters + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +--- + +## hal config provider cloudrun edit + +Edit Spinnaker's cloud run configuration. + +#### Usage + +``` +hal config provider cloudrun edit [parameters] +``` + +#### Parameters + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--gcloudPath`: The path to the gcloud executable on the machine running clouddriver. +- `--no-validate`: (_Default_: `false`) Skip validation. + +--- + +## hal config provider cloudrun enable + +Set the cloudrun provider as enabled + +#### Usage + +``` +hal config provider cloudrun enable [parameters] +``` + +#### Parameters + +- `--deployment`: If supplied, use this Halyard deployment. This will _not_ create a new deployment. +- `--no-validate`: (_Default_: `false`) Skip validation. + +--- + ## hal config provider dcos Manage and view Spinnaker configuration for the dcos provider diff --git a/content/en/docs/reference/providers/cloudrun.md b/content/en/docs/reference/providers/cloudrun.md new file mode 100644 index 00000000..4604d144 --- /dev/null +++ b/content/en/docs/reference/providers/cloudrun.md @@ -0,0 +1,102 @@ +--- +title: "Google Cloud Run" +linkTitle: "Google Cloud Run" +description: Learn how Spinnaker functionality maps to Google Cloud Run. +--- + +> If you are not familiar with Cloud Run or any of the terms used below, please consult Cloud Run's [reference documentation](https://cloud.google.com/run/docs). + +## Resource mapping + +### Account +A Spinnaker **account** maps to a single Cloud Run **application**, a top-level resource that contains +services, versions, and instances. Spinnaker authenticates itself with Cloud Run +using service account credentials for a Google Cloud Platform project - +see the [setup guide](/docs/setup/install/providers/cloudrun). + +### Load Balancer +A Spinnaker **load balancer** maps to an Cloud Run **service**. + +A service has many versions (discussed [below](#server-group)), and a version's `app.yaml` determines the service +it belongs to. If a version's `app.yaml` does not specify the name of a service, it will be deployed to the service named `default`. + +Spinnaker cannot create a service, but if a service does not exist when a version is deployed, it will be created automatically. + +A service's **traffic split** determines how incoming traffic is allocated between versions. + +### Server Group +A Spinnaker **server group** maps to an Cloud Run **version**. An `app.yaml` file (which typically lives alongside your application source code) determines +a version's configuration. If necessary, you can provide Spinnaker with the contents of an `app.yaml` +file when you deploy a version. + + +### Instance +A Spinnaker **instance** maps to an Cloud Run **instance**. + +## Operation mapping + +### Deploy + +Deploys an Cloud Run version. + +At a high level, deploying to Cloud Run using Spinnaker has three steps: + +1. You provide Spinnaker with a reference to a git repository, and some information about where your application lives + inside that repository (e.g., branch). +2. Spinnaker clones your repository and finds your application. +3. Spinnaker deploys your application to a new version by executing `gcloud run deploy`. + +If your pipeline includes a Deploy stage and has been triggered by a webhook or Jenkins job, you can dynamically resolve the git repository branch that Spinnaker uses to deploy. + +### Destroy + +Destroys a version. + +If a version is serving traffic, it will first be [disabled](#disable). + +You cannot destroy a version if it is the only version serving traffic from a service. + +### Enable + +Sets a version's traffic allocation to 100%. + +This operation is provided as a convenience method. If +you would like more fine-grained control over your versions' traffic allocations, see [Edit Load Balancer](#edit-load-balancer). + +### Disable + +Sets a version's traffic allocation to 0%, and sets the other enabled versions' allocations to their +relative proportions before the disable operation. + +This operation is provided as a convenience method, and because it is used implicitly when destroying a version. If you would like more fine-grained control over your versions' traffic allocations, see [Edit Load Balancer](#edit-load-balancer). + +You cannot disable a version if it is the only version serving traffic from a service. + +### Start + +Starts an Cloud Run version - i.e., allows a version to scale according to its scaling policy. + +This operation is only available if the version uses manual or basic scaling, or is running in the flexible environment. + +### Stop + +Stops an Cloud Run version - i.e., scales a version down to zero instances. + +This operation is only available if the version uses manual or basic scaling, or is running in the flexible environment. + +### Edit Load Balancer + +Edits a service's traffic split - i.e., the relative proportion of traffic that each version receives. + +If your pipeline includes an Edit Load Balancer stage, you can resolve the targets of a traffic split dynamically. + +### Delete Load Balancer + +Deletes a service. Deleting a service will also delete all of its versions. + +You cannot delete the `default` service. However, you can disable your Cloud Run application from within the +[Google Cloud Console](https://console.cloud.google.com). + +### Terminate instance + +Deletes an instance. diff --git a/content/en/docs/setup/install/providers/cloudrun.md b/content/en/docs/setup/install/providers/cloudrun.md new file mode 100644 index 00000000..d032c3fe --- /dev/null +++ b/content/en/docs/setup/install/providers/cloudrun.md @@ -0,0 +1,153 @@ +--- +title: "Google Cloud Run" +description: Spinnaker supports deploying applications to Google Cloud Run. +aliases: + - /setup/providers/cloudrun/ +--- + + + +In [Google Cloud Run](https://cloud.google.com/run), an +[Account](/docs/concepts/providers/#accounts) maps to a credential able to +authenticate against a given [Google Cloud +Platform](https://cloud.google.com) project. + +## Prerequisites + +You need a [Google Cloud Platform](https://cloud.google.com/) +project to run Spinnaker against. The next steps assume you've already [created +a project](https://cloud.google.com/resource-manager/docs/creating-managing-projects), +and installed [gcloud](https://cloud.google.com/sdk/downloads). +You can check that `gcloud` is installed and authenticated by running: + +```bash +gcloud info +``` + +To initialize the gcloud CLI, run the following command: + +```bash +gcloud init +``` + +If this is your first time deploying to Cloud Run in your project, create a Cloud Run application. + +To set the default project for your Cloud Run service: + +```bash +gcloud config set project +``` + +> NOTE: Replace PROJECT_ID with the name of the project you created. + + +Enable the Cloud Run Admin API: + +```bash +gcloud services enable run.googleapis.com +``` + +For Cloud Build to be able to build your sources, grant the Cloud Build Service Account role to the Compute Engine default service account by running the following: + +```bash +gcloud projects add-iam-policy-binding \ + --member=serviceAccount:-compute@developer.gserviceaccount.com \ + --role=roles/cloudbuild.builds.builder +``` + +> NOTE: Replace PROJECT_NUMBER with your Google Cloud project number, and PROJECT_ID with your Google Cloud project ID. + + +## Downloading credentials + +Spinnaker does not need to be given [service account](https://cloud.google.com/compute/docs/access/service-accounts) +credentials if it is running on a Google Compute Engine VM whose +application default credentials have sufficient scopes to deploy to Cloud Run _and_ +Spinnaker is deploying to an Cloud Run application inside the same Google Cloud Platform project in which it is running. If +Spinnaker does not need to be given service account credentials, or if you already have such a service account +with the corresponding JSON key downloaded, skip ahead to [Adding an Account](#adding-an-account). + +Run the following commands to create a service account +with the `roles/run.admin` and `roles/storage.admin` roles enabled: + +```bash +SERVICE_ACCOUNT_NAME=spinnaker-cloudrun-account +SERVICE_ACCOUNT_DEST=~/.gcp/cloudrun-account.json + +gcloud iam service-accounts create \ + $SERVICE_ACCOUNT_NAME \ + --display-name $SERVICE_ACCOUNT_NAME + +SA_EMAIL=$(gcloud iam service-accounts list \ + --filter="displayName:$SERVICE_ACCOUNT_NAME" \ + --format='value(email)') + +PROJECT=$(gcloud config get-value project) + +gcloud projects add-iam-policy-binding $PROJECT \ + --role roles/storage.admin \ + --member serviceAccount:$SA_EMAIL + +gcloud projects add-iam-policy-binding $PROJECT \ + --role roles/run.admin \ + --member serviceAccount:$SA_EMAIL + +mkdir -p $(dirname $SERVICE_ACCOUNT_DEST) + +gcloud iam service-accounts keys create $SERVICE_ACCOUNT_DEST \ + --iam-account $SA_EMAIL +``` + +Your service account JSON key now sits inside `$SERVICE_ACCOUNT_DEST`. + +## Adding an account + +First, make sure that the provider is enabled: + +```bash +hal config provider cloudrun enable +``` + +Next, run the following `hal` command to add an account named `my-cloudrun-account` to your list of Cloud Run accounts: + +```bash +hal config provider cloudrun account add my-cloudrun-account \ + --project $PROJECT \ + --json-path $SERVICE_ACCOUNT_DEST +``` + +You can omit the `--json-path` flag if Spinnaker does not need service account credentials. + +## Deploying to Cloud Run + +### Deploying from Git + +Spinnaker supports deploying your source code to Cloud Run by cloning your application's git +repository and submitting it to Cloud Run. Unless your code is public, Spinnaker needs a mechanism to +authenticate with your repositories - many of the configuration flags for Cloud Run manage this +authentication. + +You can view the available configuration flags for Cloud Run within the +[Halyard reference](/docs/reference/halyard/commands#hal-config-provider-cloudrun-account-add). + +### Deploying from storage + +Much like deploying from Git, Spinnaker also supports deploying your source code to Cloud Run +from a Google Cloud Storage bucket. This method of deploying requires you to bundle your code +into a .tar archive and then store that on GCS. When the deploy stage executes, Spinnaker will +fetch your tar archive, untar it, and then deploy the code to Cloud Run. + +### Deploying from Google Container Registry URL + +Spinnaker supports deploying Docker containers on the Cloud Run runtime from images built and stored +in Google Container Registry from just a gcr.io URL. + +You'll find an option in the Create Server Group dialog in Deck to use a **Container Image** as a +deployment's **Source Type**. Selecting the **Container Image** option reveals a textbox that can then be used to specify the gcr.io URL. Alternatively +you can use an **Artifact** as the source of the container image URL. + +## Next steps + +Optionally, you can [set up another cloud provider](/docs/setup/install/providers/), +but otherwise you're ready to [choose an environment](/docs/setup/install/environment/) +in which to install Spinnaker.