Push Docker Images to Google Artifact Registry

Initial Setup: Connecting to Google Cloud

Before we can interact with Google Cloud services, we need to install and configure the Google Cloud command-line interface (gcloud). This tool will allow us to manage our cloud resources directly from the terminal.

If you haven't already, you'll need to:

1. Create a Google Cloud account and a new project. You can follow Google's official guide for this. Make a note of your Project ID.
2. Install the Google Cloud CLI by following the instructions for your operating system in the official documentation.

Once the CLI is installed, we need to initialize it and authenticate your account.

After completing these steps, your local environment is configured to communicate with your Google Cloud project.

Step 1: Create a Repository in Artifact Registry

Our first action in the cloud is to create a repository—a dedicated space to store our Docker images.

A repository needs a few configuration details:

• Name: A unique name for the repository (e.g., fastapi-apps).
• Format: The type of package it will store. For us, this is Docker.
• Location: The geographic region where your images will be stored. It's best practice to choose a region close to where you'll run your services (e.g., us-central1, europe-west2).

Let's watch a short video that demonstrates how to create a repository using the Google Cloud web console, which is a very intuitive way to start.

While the UI is great for visualization, you can also perform this step using the gcloud CLI. This is often faster and more scriptable. The command looks like this:

gcloud services enable artifactregistry.googleapis.com

gcloud artifacts repositories create YOUR_REPO_NAME \
    --repository-format=docker \
    --location=YOUR_CHOSEN_LOCATION \
    --description="Repository for FastAPI applications"

• Replace YOUR_REPO_NAME with the name you decided on (e.g., fastapi-apps).
• Replace YOUR_CHOSEN_LOCATION with the region you selected (e.g., europe-west2).

Step 2: Authenticate Docker with Artifact Registry

Now that we have a repository, we need to grant your local Docker client permission to push images to it. You don't need to manually handle passwords or tokens; the gcloud CLI can configure this for you automatically.

This command updates your Docker configuration file (~/.docker/config.json) to use gcloud as a credential helper for your specific Artifact Registry location. This means any docker push or docker pull command targeting that registry will automatically use your logged-in Google Cloud credentials.

Step 3: Tag Your Docker Image

Before pushing, we need to "tag" our local image with its full destination name. This special tag tells Docker exactly where to send the image: which registry, which project, which repository, and what to call it.

The naming convention for Artifact Registry is very specific:
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

Let's break this down:

• LOCATION: The region you chose for your repository (e.g., europe-west2).
• PROJECT-ID: Your unique Google Cloud Project ID.
• REPOSITORY: The name of the repository you created (e.g., fastapi-apps).
• IMAGE: The name you want to give your image in the registry (e.g., my-fastapi-app).
• TAG: A version identifier, like v1 or latest.

Assuming you have the Docker image fastapi-app:latest that we built in the previous module, you would tag it using the following command.

docker tag fastapi-app:latest YOUR_LOCATION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPO_NAME/my-fastapi-app:v1

Example:
If your location is us-central1, your project ID is cool-project-123, and your repository is fastapi-apps, the command would be:

docker tag fastapi-app:latest us-central1-docker.pkg.dev/cool-project-123/fastapi-apps/my-fastapi-app:v1

Run docker images after this command. You will see a new image listed with the long Artifact Registry name, but it will share the same Image ID as your original fastapi-app:latest, proving it's just a new tag, not a duplicate image.

Step 4: Push the Image to the Registry

With the authentication configured and the image correctly tagged, the final step is to push it.

docker push YOUR_LOCATION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPO_NAME/my-fastapi-app:v1

Use the exact same long tag you used in the docker tag command. Docker will now upload the image layers to your private repository in Artifact Registry.

Step 5: Verify the Push

The final step is to confirm that the image has arrived safely in your repository. You can do this in two ways:

1. Using the Google Cloud Console (UI)
Navigate to Artifact Registry in your Google Cloud Console, click on your repository, and you should see your newly pushed image listed.

2. Using the gcloud CLI
To verify from your terminal, you can list the images in your repository.

gcloud artifacts docker images list YOUR_LOCATION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPO_NAME

This command should output a table that includes your my-fastapi-app image.

Conclusion

Congratulations! You have successfully pushed your FastAPI application's Docker image from your local machine to a secure, private container registry in the cloud.

Key Takeaways:

• Artifact Registry is Google Cloud's service for storing and managing container images and other software packages.
• The workflow for pushing an image is:
  1. Create a Repository: A dedicated space for your images.
  2. Authenticate Docker: Use gcloud auth configure-docker to give Docker permission to access the registry.
  3. Tag the Image: Apply a special tag with the full path to the registry: LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG.
  4. Push the Image: Use docker push with the full tag to upload your image.

Your containerized application is now stored in the cloud and is ready to be deployed. In our next lesson, we will perform the final step: deploying the container image from Artifact Registry to Google Cloud Run to bring our API to life with a public URL.