Skip to content

Commit

Permalink
Merge pull request #481 from GoogleCloudPlatform/documentation-update
Browse files Browse the repository at this point in the history
Documentation update
  • Loading branch information
anindyatahsin authored Sep 24, 2024
2 parents 1b38625 + f1917d7 commit 861e1d2
Showing 1 changed file with 51 additions and 220 deletions.
271 changes: 51 additions & 220 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,235 +1,66 @@
The Google Cloud CLI Docker image lets you pull a specific version of gcloud CLI as a Docker image from [Artifact Registry](https://cloud.google.com/artifact-registry) and quickly execute Google Cloud CLI commands in an isolated, correctly configured container.

You can refer to the image's [documentation page](https://cloud.google.com/sdk/docs/downloads-docker) for complete details.

# Google Cloud CLI Docker

The Google Cloud CLI Docker Images (comprising the `:stable`, `:latest`, `:slim`, `:alpine`, `:emulators`, and `:debian_component_based` images located within this repository) are a set of images enabling the usage of the Google Cloud CLI as well as its bundled components.
The Google Cloud CLI Docker image is the gcloud CLI installed on top of a Debian or Alpine image. The Google Cloud CLI Docker Images enable the usage of gcloud as well as its bundled components without having to manually install gcloud in your local machine.

## Docker image options

There are six Google Cloud Docker images. We recommend that you install
the following stable image:

* `:stable`, `:VERSION-stable`: Default, Smallest (Debian-based) image with a
standard gcloud installation.

The `:stable` tag is Debian-based and includes default command
line tools of Google Cloud CLI (`gcloud`, `gsutil`, `bq`). [Additional components](https://cloud.google.com/sdk/docs/install#deb) can also be installed using the INSTALL_COMPONENTS build argument.
If you want to use an Alpine-based image, you can install the following
image:

## Repositories
The Google Cloud CLI Docker Image is hosted on [Artifact Registry](https://console.cloud.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli).
* `:alpine`, `:VERSION-alpine`: Smaller (Alpine-based) image with no additional
components installed. This image supports linux/arm.

The full repository name for Artifact Registry is `gcr.io/google.com/cloudsdktool/google-cloud-cli`.
If you want images with additional packages or gcloud components pre-installed,
you can install one of the following options:

## Supported tags
* `:emulators`, `:VERSION-emulators`: Smaller (Debian-based) image with emulator
components pre-installed.
* `:latest`, `:VERSION`: Large (Debian-based) image with additional components
pre-installed.
* `:slim`, `:VERSION-slim`: Smaller (Debian-based) image with no components
pre-installed.
* `:debian_component_based`, `:VERSION-debian_component_based`: Large (Debian-based)
image with additional components pre-installed. As opposed to `:latest` which
used deb packages, this image uses the component manager to install components.
This image supports linux/arm.

* `:stable`, `:VERSION-stable`: (default image with a standard gcloud installation, Debian-based)
* `:latest`, `:VERSION`: (large image with
additional components pre-installed, Debian-based)
* `:slim`, `:VERSION-slim`: (smaller image with
no components pre-installed, Debian-based)
* `:alpine`, `:VERSION-alpine`: (smallest image
with no additional components installed, Alpine-based)
* `:debian_component_based`, `:VERSION-debian_component_based`: (Similar to
:latest but component installer based)
* `:emulators`, `:VERSION`: (as small as possible with all the emulators)
## Installing a Docker image

→ Check out [Artifact Registry](https://console.cloud.corp.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli) for available tags.
The Docker image is hosted on
[Artifact Registry](https://console.cloud.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli)
with the following repository name:
`gcr.io/google.com/cloudsdktool/google-cloud-cli`. The images are also available
using the `us.gcr.io`, `eu.gcr.io`, and `asia.gcr.io` repositories.

## Usage
1. To use the image of the stable Google Cloud CLI release,
`gcr.io/google.com/cloudsdktool/google-cloud-cli:stable`,
pull it from [Artifact Registry](https://console.cloud.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli)
by running the following command:

To use this image, pull from [Artifact Registry](https://pantheon.corp.google.com/artifacts/docker/google.com:cloudsdktool/us/gcr.io/google-cloud-cli) and then run the following command:
```none
docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable
```

```
docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
```
1. Verify the installation by running:

Verify the install
```none
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable gcloud version
```

```bash
docker run gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version
Google Cloud CLI 485.0.0
```
If you have used the floating `:stable` tag (which always point to the latest
release), verify the installation by running the following command:

or use a particular version number (485.0.0 or greater for `:stable`):
```none
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version
```

```bash
docker run gcr.io/google.com/cloudsdktool/google-cloud-cli:stable-485.0.0 gcloud version
```

You can authenticate `gcloud` with your user credentials by running [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login):

```
docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli gcloud auth login
```

If you need to authenticate any program that uses the Google Cloud APIs, you need to pass the `--update-adc` option:

```
docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli gcloud auth login --update-adc
```

If you want to use a specific project for future uses, you can set this inside the `gcloud-config` container:

```
docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli /bin/bash -c 'gcloud auth login && gcloud config set project your-project'
```

Once you authenticate successfully, credentials are preserved in the volume of
the `gcloud-config` container.

To list compute instances using these credentials, run the container with
`--volumes-from`:

```
docker run --rm --volumes-from gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli gcloud compute instances list --project your_project
NAME ZONE MACHINE_TYPE PREEMPTIBLE INTERNAL_IP EXTERNAL_IP STATUS
instance-1 us-central1-a n1-standard-1 10.240.0.2 8.34.219.29 RUNNING
```

> :warning: **Warning:** The `gcloud-config` container now has a volume
> containing your Google Cloud credentials. Do not use `gcloud-config` volume in
> other containers.

Alternatively, you can use `auth/credential_file_override` property to set a path to a mounted service account
and then the config to read that using `CLOUDSDK_CONFIG` environment variable.

for example, `mycloud` configuration below has the `auth/credential_file_override` already set and points towards a certificate file
that will be present within the container as a separate volume mount.

> See [issue#152](https://github.com/GoogleCloudPlatform/cloud-sdk-docker/issues/152#event-1933393673)
```
$ docker run -ti -e CLOUDSDK_CONFIG=/config/mygcloud \
-v `pwd`/mygcloud:/config/mygcloud \
-v `pwd`:/certs gcr.io/google.com/cloudsdktool/google-cloud-cli:alpine /bin/bash
bash-4.4# gcloud config list
[auth]
credential_file_override = /certs/svc_account.json
bash-4.4# head -10 /certs/svc_account.json
{
"type": "service_account",
"project_id": "project_id1",
....
bash-4.4# gcloud projects list
PROJECT_ID NAME PROJECT_NUMBER
project_id1 GCPAppID 1071284184432
```
You can set any Cloud SDK property via an ENV,
[please read](https://cloud.google.com/sdk/docs/properties#setting_properties_using_environment_variables) and [here.](https://cloud.google.com/sdk/gcloud/reference/config)

### Components Installed in Each Tag

| Component | :latest | :alpine | :slim | :debian_component_based | :emulators |
|:----------------------------------------------------:|:-------:|:-------:|:-----:|:-----------------------:|:----------:|
| App Engine Go Extensions | x | | | x | |
| Appctl | | | | x | |
| Artifact Registry Go Module Package Helper | | | | | |
| BigQuery Command Line Tool | x | x | x | x | x |
| Bundled Python 3.9 | x | x | x | x | x |
| Cloud Bigtable Command Line Tool | x | | | x | |
| Cloud Bigtable Emulator | x | | | x | x |
| Cloud Datastore Emulator | x | | | x | x |
| Cloud Firestore Emulator | x | | | | x |
| Cloud Pub/Sub Emulator | x | | | x | x |
| Cloud Run Proxy | | | | | |
| Cloud SQL Proxy | | | | | |
| Cloud Spanner Emulator | x | | | | x |
| Cloud Spanner Migration Tool | | | | | |
| Cloud Storage Command Line Tool | x | x | x | x | x |
| Google Cloud CLI Core Libraries | x | x | x | x | x |
| Google Cloud CRC32C Hash Tool | x | x | x | x | x |
| Google Container Registry's Docker credential helper | | | | | |
| Kustomize | | | | x | |
| Log Streaming | | | | | |
| Minikube | | | | x | |
| Nomos CLI | | | | x | |
| On-Demand Scanning API extraction helper | x | | | x | |
| Skaffold | | | | x | |
| Terraform Tools | | | | | |
| anthos-auth | | | | x | |
| config-connector | | | | | |
| gcloud Alpha Commands | x | | x | x | |
| gcloud Beta Commands | x | | x | x | x |
| gcloud app Java Extensions | x | | | x | |
| gcloud app Python Extensions | x | | | x | |
| gcloud app Python Extensions (Extra Libraries) | x | | | x | |
| gke-gcloud-auth-plugin | x | | | x | |
| kpt | x | | | x | |
| kubectl | x | | | x | |
| kubectl-oidc | | | | | |
| pkg | | | | | |


### Installing additional components

#### Debian-based images

```
cd stable/
docker build --build-arg CLOUD_SDK_VERSION=485.0.0 \
--build-arg INSTALL_COMPONENTS="google-cloud-cli-datastore-emulator=485.0.0-0" \
-t my-cloud-sdk-docker:stable .
```

```
cd debian_slim/
docker build --build-arg CLOUD_SDK_VERSION=485.0.0 \
--build-arg INSTALL_COMPONENTS="google-cloud-cli-datastore-emulator=485.0.0-0" \
-t my-cloud-sdk-docker:slim .
```

#### Alpine-based images

To install additional components for Alpine-based images, create a Dockerfile
that uses the `cloud-sdk` image as the base image. For example, to add `kubectl` and
`app-engine-java` components:

```Dockerfile
FROM gcr.io/google.com/cloudsdktool/google-cloud-cli:alpine
RUN apk --update add gcompat openjdk8-jre
RUN gcloud components install app-engine-java kubectl
```

and run:

```
docker build -t my-cloud-sdk-docker:alpine .
```

Note that in this case, you have to install dependencies of additional
components manually.

### Installing different version of gcloud sdk:
```
docker build -t my-cloud-sdk-docker:alpine --build-arg CLOUD_SDK_VERSION=<release_number> .
```

### Legacy image (Google App Engine based)

The original image in this repository was based off of

> FROM gcr.io/google_appengine/base
The full Dockerfile for that can be found
[here](google_appengine_base/Dockerfile) for archival as well as in image tag
`google/cloud-sdk-docker:legacy`

### Cloud SDK Release Tracking

You can also follow the Cloud SDK Release schedule here
- [https://groups.google.com/forum/#!forum/google-cloud-sdk-announce](https://groups.google.com/forum/#!forum/google-cloud-sdk-announce)

## Support

The Google Cloud CLI Team works to ensure that the images within this repository provide fully functional installs of the Google Cloud CLI. This work includes addressing any bugs or issues that prevent the execution of the `gcloud` command line tool or components installed by default on each image. The team also works to ensure that third party packages necessary for the function of the Google Cloud CLI are using stable release versions, and that base OS images are updated to recent, stable releases in a timely manner.

For workflows separate from or unrelated to the execution of the Cloud CLI that require additional or different dependencies, the Cloud CLI team recommends creating your own image layer on top of the Cloud CLI Docker Image where you can remove and install dependencies as needed. The Cloud CLI Team will not address issues related to workflows or tools unrelated to the execution of the Google Cloud CLI. Similarly, the team will deny requests for additional packages or tooling unrelated to the intended functioning of the Google Cloud CLI.

### Identifying Vulnerabilities

If you or your organization have detected vulnerabilities within any of the Cloud CLI Docker Images, please [file a bug.](https://issuetracker.google.com/issues/new?component=187143) Your bug must contain the type of each vulnerability and the **exact location within the image where each is present**. Vulnerabilities within base OS images will not be addressed beyond ensuring the Cloud CLI Docker images are using recent, stable releases of Debian or Alpine Linux.

### Pinning version

Images tagged `:latest`, `:alpine`, `:slim` and `:debian_component_based` use
the most recent version of Google Cloud SDK, which may change its behaviour in
the future. List of components installed by default in each image can also
change between versions. To avoid such changes breaking the tool you are using,
it is not recommended to use these tags in any production tools directly.
Instead use a particular version as listed in [Supported tags](#supported-tags)
and update it periodically.

0 comments on commit 861e1d2

Please sign in to comment.