diff --git a/README.md b/README.md index c1b80f9..e6111d0 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# SAS Viya 4 Infrastructure as Code (IaC) for Google Cloud Platform (GCP) +# SAS Viya 4 Infrastructure as Code (IaC) for Google Cloud ## Overview -This project contains Terraform scripts to provision Google GCP infrastructure resources required to deploy SAS Viya 4 platform products. Here is a list of resources this project can create - +This project contains Terraform scripts to provision Google Cloud infrastructure resources required to deploy SAS Viya 4 platform products. Here is a list of resources this project can create - >- VPC Network and Network Firewalls >- Managed Google Kubernetes Engine (GKE) cluster @@ -13,14 +13,14 @@ This project contains Terraform scripts to provision Google GCP infrastructure r [Architecture Diagram](./docs/images/viya4-iac-gcp-diag.png?raw=true) -Once the cloud resources are provisioned, see the [viya4-deployment](https://github.com/sassoftware/viya4-deployment) repo to deploy SAS Viya 4 platform products. If you need more information on the SAS Viya 4 platform products refer to the official [SAS® Viya® platform Operations](https://documentation.sas.com/?cdcId=itopscdc&cdcVersion=default&docsetId=itopswlcm&docsetTarget=home.htm) documentation for more details. +Once the cloud resources are provisioned, see the [viya4-deployment](https://github.com/sassoftware/viya4-deployment) repository to deploy SAS Viya 4 platform products. If you need more information on the SAS Viya 4 platform products refer to the official [SAS® Viya® platform Operations](https://documentation.sas.com/?cdcId=itopscdc&cdcVersion=default&docsetId=itopswlcm&docsetTarget=home.htm) documentation for more details. ## Prerequisites Operational knowledge of - [Terraform](https://www.terraform.io/intro/index.html) - [Docker](https://www.docker.com/) -- [Google Cloud Platform](https://cloud.google.com/) +- [Google Cloud](https://cloud.google.com/) - [Kubernetes](https://kubernetes.io/docs/concepts/) ### Required @@ -46,28 +46,28 @@ Operational knowledge of Run these commands in a Terminal session: ```bash -# clone this repo +# clone this repository git clone https://github.com/sassoftware/viya4-iac-gcp # move to directory cd viya4-iac-gcp ``` -### Authenticating Terraform to access GCP +### Authenticating Terraform to access Google Cloud -See [Terraform GCP Authentication](./docs/user/TerraformGCPAuthentication.md) for details. +See [Terraform Google Cloud Authentication](./docs/user/TerraformGCPAuthentication.md) for details. ### Customize Input Values Create a file named `terraform.tfvars` to customize any input variable value documented in the [CONFIG-VARS.md](docs/CONFIG-VARS.md) file. For starters, you can copy one of the provided example variable definition files in `./examples` folder. For more details on the variables declared refer to the [CONFIG-VARS.md](docs/CONFIG-VARS.md) file. -**NOTE:** You will need to update the `cidr_blocks` in the [variables.tf](variables.tf) file to allow traffic from your current network. Without these rules, access to the cluster will only be allowed via the GCP Console. +**NOTE:** You will need to update the `cidr_blocks` in the [variables.tf](variables.tf) file to allow traffic from your current network. Without these rules, access to the cluster will only be allowed via the Google Cloud Console. When using a variable definition file other than `terraform.tfvars`, see [Advanced Terraform Usage](docs/user/AdvancedTerraformUsage.md) for additional command options. ## Creating and Managing the Cloud Resources -Create and manage the GCP cloud resources by either +Create and manage the Google Cloud resources by either - using [Terraform](docs/user/TerraformUsage.md) directly on your workstation, or - using a [Docker container](docs/user/DockerUsage.md). @@ -87,11 +87,11 @@ See [troubleshooting](./docs/Troubleshooting.md) page. ## Additional Resources -### GCP +### Google Cloud - Google Cloud CLI - https://cloud.google.com/sdk/gcloud -- Terraform on GCP - https://cloud.google.com/docs/terraform -- Terraform and GCP Service Accounts - https://medium.com/@gmusumeci/how-to-create-a-service-account-for-terraform-in-gcp-google-cloud-platform-f75a0cf918d1 +- Terraform on Google Cloud - https://cloud.google.com/docs/terraform +- Terraform and Google Cloud Service Accounts - https://medium.com/@gmusumeci/how-to-create-a-service-account-for-terraform-in-gcp-google-cloud-platform-f75a0cf918d1 - GKE intro - https://cloud.google.com/kubernetes-engine ### Terraform diff --git a/docs/CONFIG-VARS.md b/docs/CONFIG-VARS.md index f9ec92a..9f80726 100644 --- a/docs/CONFIG-VARS.md +++ b/docs/CONFIG-VARS.md @@ -7,7 +7,7 @@ Supported configuration variables are listed in the table below. All variables - [List of valid configuration variables](#list-of-valid-configuration-variables) - [Table of Contents](#table-of-contents) - [Required Variables](#required-variables) - - [GCP Authentication](#gcp-authentication) + - [Google Cloud Authentication](#gcp-authentication) - [Admin Access](#admin-access) - [Networking](#networking) - [Use Existing](#use-existing) @@ -31,21 +31,21 @@ Terraform input variables can be set in the following ways: | Name | Description | Type | Default | Notes | | :--- | :--- | :--- | :--- | :--- | -| prefix | A prefix used in the name of all the GCP resources created by this script. | string | | The prefix string must start with a lowercase letter and contain only lowercase alphanumeric characters and dashes (-), but cannot end with a dash. | -| location | The GCP Region (for example "us-east1") or GCP Zone (for example "us-east1-b") to provision all resources in this script. | string | | See [this topic](user/Locations.md) on how to chose a region or a zone. | -| project | The ID of the GCP Project to use | string | | | +| prefix | A prefix used in the name of all the Google Cloud resources created by this script. | string | | The prefix string must start with a lowercase letter and contain only lowercase alphanumeric characters and dashes (-), but cannot end with a dash. | +| location | The Google Cloud Region (for example "us-east1") or Google Cloud Zone (for example "us-east1-b") to provision all resources in this script. | string | | See [this topic](user/Locations.md) on how to chose a region or a zone. | +| project | The ID of the Google Cloud Project to use | string | | | | service_account_keyfile | Filename of the Service Account JSON file | string | Not required when running on a Google Cloud VM that is associated with the Service Account | -## GCP Authentication +## Google Cloud Authentication -The Terraform process manages GCP resources on your behalf. In order to do so, it needs to know the credentials for a GCP identity with the required permissions. +The Terraform process manages Google Cloud resources on your behalf. In order to do so, it needs to know the credentials for a Google Cloud identity with the required permissions. -For more detailed information on what is needed see [Authenticating Terraform to access GCP](https://github.com/sassoftware/viya4-iac-gcp/blob/main/docs/user/TerraformGCPAuthentication.md) +For more detailed information on what is needed see [Authenticating Terraform to access Google Cloud](https://github.com/sassoftware/viya4-iac-gcp/blob/main/docs/user/TerraformGCPAuthentication.md) ## Admin Access -By default, the API of the GCP resources that are being created are only accessible through authenticated GCP clients (e.g. the Google Cloud Portal, the `gcloud` CLI, the Google Cloud Shell, etc.) -To allow access for other administrative client applications (for example `kubectl`, `psql`, etc.), you need to open up the GCP firewall to allow access from your source IPs. +By default, the API of the Google Cloud resources that are being created are only accessible through authenticated Google Cloud clients (e.g. the Google Cloud Portal, the `gcloud` CLI, the Google Cloud Shell, etc.) +To allow access for other administrative client applications (for example `kubectl`, `psql`, etc.), you need to open up the Google Cloud firewall to allow access from your source IPs. To do set these permissions as part of this Terraform script, specify ranges of IP addresses in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). Contact your Network Administrator to find the public CIDR range of your network. @@ -94,11 +94,11 @@ subnet_names = { } ``` -Note: The subnets for filestore and database can not the pre-created. GCP creates the subnets as part of the services. +Note: The subnets for filestore and database can not the pre-created. Google Cloud creates the subnets as part of the services. ## General -The application of a Kubernetes version in GCP has some limitations when assigning channels and versions to the cluster. The doc outlining on these limitations can be found in the [Kubernetes Versions](user/KubernetesVersions.md) guide. +The application of a Kubernetes version in Google Cloud has some limitations when assigning channels and versions to the cluster. The documentation that describes these limitations can be found in the [Kubernetes Versions](user/KubernetesVersions.md) guide. | Name | Description | Type | Default | Notes | | :--- | ---: | ---: | ---: | ---: | @@ -114,7 +114,7 @@ The application of a Kubernetes version in GCP has some limitations when assigni | create_jump_public_ip | Add public ip to jump VM | bool | true | | | jump_vm_admin | OS Admin User for the Jump VM | string | "jumpuser" | | | jump_rwx_filestore_path | File store mount point on Jump server | string | "/viya-share" | | -| tags | Map of common tags to be placed on all GCP resources created by this script | map | {} | | +| tags | Map of common tags to be placed on all Google Cloud resources created by this script | map | {} | | | ssh_public_key | File name of public ssh key for jump and nfs VM | string | null | Required with `create_jump_vm=true` or `storage_type=standard` | | cluster_api_mode | Public or private IP for the cluster api| string|"public"|Valid Values: "public", "private" | diff --git a/docs/user/DockerUsage.md b/docs/user/DockerUsage.md index dbe17b7..766e33f 100644 --- a/docs/user/DockerUsage.md +++ b/docs/user/DockerUsage.md @@ -31,14 +31,14 @@ docker build --build-arg INSTALL_COMPONENTS="cloud-spanner-emulator" -t viya4-ia ``` -### Service Account Keyfile for GCP Authentication +### Service Account Keyfile for Google Cloud Authentication -Prepare a file with GCP authentication info, as described in [Authenticating Terraform to access GCP](./TerraformGCPAuthentication.md) and store it outside of this repo in a secure file, for example `$HOME/.viya4-tf-gcp-service-account.json`. +Prepare a file with Google Cloud authentication information, as described in [Authenticating Terraform to access Google Cloud](./TerraformGCPAuthentication.md) and store it outside of this repository in a secure file, for example `$HOME/.viya4-tf-gcp-service-account.json`. ### Docker Volume Mounts Add volume mounts to the `docker run` command for all files and directories that must be accessible from inside the container. -- `--volume=$HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json` Service Account Key file for GCP authentication +- `--volume=$HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json` Service Account Key file for Google Cloud authentication - `--volume=$HOME/.ssh:/.ssh` for [`ssh_public_key`](../CONFIG-VARS.md#required-variables) variable in the `terraform.tfvars` file - `--volume=$(pwd):/workspace` for local directory where `terraform.tfvars` file resides and where `terraform.tfstate` file will be written. To grant Docker, permission to write to the local directory use [`--user` option](https://docs.docker.com/engine/reference/run/#user) diff --git a/docs/user/KubernetesVersions.md b/docs/user/KubernetesVersions.md index c1f3901..e3d259e 100644 --- a/docs/user/KubernetesVersions.md +++ b/docs/user/KubernetesVersions.md @@ -1,6 +1,6 @@ # Kubernetes Versions -Setting versions within the Google Cloud Platform (GCP) environment is slightly different from setting a version within other cloud providers +Setting versions within the Google Cloud environment is slightly different from setting a version within other cloud providers There are two scenarios that are supported. These are: diff --git a/docs/user/Locations.md b/docs/user/Locations.md index 1937c4c..4dc1d4d 100644 --- a/docs/user/Locations.md +++ b/docs/user/Locations.md @@ -1,6 +1,6 @@ ## Resource Locations -Google Cloud Platform resources are hosted in different data centers worldwide, divided into [Regions and Zones](https://cloud.google.com/compute/docs/regions-zones). +Google Cloud resources are hosted in different data centers worldwide, divided into [Regions and Zones](https://cloud.google.com/compute/docs/regions-zones). You control the location of your Viya4 IAC resources by setting the `location` variable to either a Region or a Zone. diff --git a/docs/user/TerraformGCPAuthentication.md b/docs/user/TerraformGCPAuthentication.md index e4e448d..441cd12 100644 --- a/docs/user/TerraformGCPAuthentication.md +++ b/docs/user/TerraformGCPAuthentication.md @@ -1,9 +1,9 @@ -# Authenticating Terraform to access GCP +# Authenticating Terraform to access Google Cloud -Terraform creates and destroys resources in the Google Cloud Platform on your behalf. -In order to do so, it needs to authenticate itself to GCP with the appropriate permissions. +Terraform creates and destroys resources in Google Cloud on your behalf. +In order to do so, it needs to authenticate itself to Google Cloud with the appropriate permissions. -This project uses a GCP Service Account to authenticate with GCP. You will need a Service Account with the appropriate permissions. You can use an existing Service Account, or preferably create a dedicated Service Account. +This project uses a Google Cloud Service Account to authenticate with Google Cloud. You will need a Service Account with the appropriate permissions. You can use an existing Service Account, or preferably create a dedicated Service Account. ## Running Terraform outside Google Cloud @@ -14,9 +14,9 @@ If you are running terraform outside of Google Cloud, generate a service account If you are running terraform on a VM in Google Cloud, you can [configure that VM instance to use your Service Account](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances#using). This will allow Terraform to authenticate to Google Cloud without having to bake in a separate credential/authentication file. Ensure that the scope of the VM is set to or includes https://www.googleapis.com/auth/cloud-platform. -## Create a GCP Service Account +## Create a Google Cloud Service Account -How to create a GCP Service Account: https://cloud.google.com/iam/docs/creating-managing-service-accounts +How to create a Google Cloud Service Account: https://cloud.google.com/iam/docs/creating-managing-service-accounts gcloud CLI Example: @@ -44,7 +44,7 @@ The Service Account will need the following [IAM roles](https://cloud.google.com | `roles/iam.serviceAccountUser` | Service Account User | Terraform Kubernetes Engine Module | | `roles/resourcemanager.projectIamAdmin` | Project IAM Admin | Terraform Kubernetes Engine Module | -How to modify IAM access to GCP resources: https://cloud.google.com/iam/docs/granting-changing-revoking-access +How to modify IAM access to Google Cloud resources: https://cloud.google.com/iam/docs/granting-changing-revoking-access gcloud CLI Example: ```bash @@ -96,7 +96,7 @@ roles/resourcemanager.projectIamAdmin ## Create the Service Account Keyfile -When running terraform on a workstation outside of the Google Cloud Platform, you persist the Service Account information to a JSON file, and then [specify that file when running terraform](#Terraform-project-variables-to-authenticate-with-GCP). +When running terraform on a workstation outside of Google Cloud, you store the Service Account information in a JSON file, and then [specify that file when running terraform](#Terraform-project-variables-to-authenticate-with-GCP). Managing key files using the Cloud Console: https://console.cloud.google.com/apis/credentials/serviceaccountkey @@ -110,11 +110,11 @@ gcloud iam service-accounts keys create ${SA_KEY_FILE} --iam-account ${SA_NAME}@ chmod 500 ${SA_KEY_FILE} # secure the keyfile ``` -## Terraform project variables to authenticate with GCP +## Terraform project variables to authenticate with Google Cloud As part of your [Terraform input variables](../../README.md#customize-input-values), set these values: | Name | Description | | :--- | :--- | -| project | The GCP Project to use | -| service_account_keyfile | Filename of the Service Account JSON file. Alternatively, you can set the `GOOGLE_APPLICATION_CREDENTIAL` environment variable. Note that you do not need to set this variable when running on a GCP VM that is associated with the Service Account. | +| project | The Google Cloud Project to use | +| service_account_keyfile | Filename of the Service Account JSON file. Alternatively, you can set the `GOOGLE_APPLICATION_CREDENTIAL` environment variable. Note that you do not need to set this variable when running on a Google Cloud VM that is associated with the Service Account. | diff --git a/docs/user/TerraformUsage.md b/docs/user/TerraformUsage.md index 3c447c6..69821a3 100644 --- a/docs/user/TerraformUsage.md +++ b/docs/user/TerraformUsage.md @@ -6,9 +6,9 @@ When using the Terraform CLI, make sure you have all the necessary tools [instal ## Preparation -### Set GCP Authentication +### Set Google Cloud Authentication -Prepare a file with authentication info, as described in [Authenticating Terraform to access GCP](./TerraformGCPAuthentication.md). +Prepare a file with authentication information, as described in [Authenticating Terraform to access Google Cloud](./TerraformGCPAuthentication.md). ### Prepare Variable Definitions (.tfvars) File