Configure VMs to install Debian packages

This page describes configuring VMs to install Debian packages from an Artifact Registry Apt repository.

Before you begin

If the target Apt repository does not exist, create a new standard or remote repository. You can create a private repository, or a public repository that doesn't require authentication.

Prepare a VM to access an Apt repository

Configure a VM to access a standard Apt repository

Configure a VM to access an Apt repository:

1. Generate the VM configuration command by running the gcloud beta artifacts print-settings apt command:

   gcloud beta artifacts print-settings apt \
       --repository=REPOSITORY \
       --location=LOCATION
   

   Replace the following:

   • LOCATION is a regional or multi-regional location.
   • REPOSITORY is the name of the Artifact Registry repository.

   The output is similar to the following:

   # To configure your package manager with this repository:
   
   # Update Apt:
   sudo apt update
   
   # Install the Apt credential helper:
   sudo apt install apt-transport-artifact-registry
   
   # Configure your VM to access Artifact Registry packages using the following
   # command:
   
   echo "deb ar+https://LOCATION-apt.pkg.dev/projects/PROJECT REPOSITORY main" | sudo tee -a /etc/apt/sources.list.d/artifact-registry.list
   
   # Update Apt:
   sudo apt update
   

2. Configure Apt to fetch packages from your repository using the echo command from the output of the print-settings command.

   For example, to install packages from the public repository my-repo in the project my-project and in the location us-central1, use the following command:

   echo 'deb ar+https://us-central1-apt.pkg.dev/projects/my-project my-repo main'
   

3. Update your repository sources with the following command:

   sudo apt update
   

Apt can now connect to the repository.

If you create additional Apt repositories, you can add them to the artifact-registry.list file and then rerun sudo apt update to update repository sources.

Configure a VM to access a remote Apt repository

To configure a VM to only use a remote Apt repository instead of a standard upstream Apt repository, replace the standard repository with your remote repository in the VM's /etc/apt/sources.list file.

1. Grant project wide Artifact Registry write permissions to the default Compute Engine service account:

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/artifactregistry.writer
   

2. Go to the VM instances page.

3. In the row with your VM, click SSH.

   A new window opens with a terminal session on the VM.

4. Open the VM's /etc/apt/sources.list file and locate the standard repository you want to replace with your new remote repository.

5. Delete the standard repository line, and replace it with the following:

   deb ar+https://LOCATION-apt.pkg.dev/remote/PROJECT_ID/REMOTE_REPOSITORY_NAME UPSTREAM_REPOSITORY_NAME COMPONENTS
   

   Replace the following:

   • LOCATION with the regional or multi-regional location of the remote repository.
   • PROJECT_ID with the project ID of the VM.
   • REMOTE_REPOSITORY_NAME with the name you gave your remote repository.
   • UPSTREAM_REPOSITORY_NAME with the name of the upstream repository for your remote.
   • COMPONENTS with a whitespace separated list of component names.

   For example, the following configures the VM to fetch packages from the repository my-repo in the project my-project in location us-east1 using buster as the upstream repository for components main, contrib, and non-free.

   deb ar+https://us-east1-apt.pkg.dev/remote/my-project/my-repo buster main contrib non-free
   

6. Update your repository sources with the following command:

   sudo apt update
   

   Apt can now connect to the repository.

Use a remote Apt repository as a backup

If you want to keep the standard upstream as the first option and add the remote repository as a fall-back option, you can keep the standard upstream in the sources.list file, and either append the remote repository to the end of the sources.list file, or create a new list in the sources.list.d folder.

To create a new artifact-registry.list file in the sources.list.dfolder, run the following command:

echo 'deb ar+https://LOCATION-apt.pkg.dev/remote/PROJECT_ID/REMOTE_REPOSITORY_NAME UPSTREAM_REPOSITORY_NAME COMPONENTS' | sudo tee -a  /etc/apt/sources.list.d/artifact-registry.list

Replace the following:

• LOCATION with the regional or multi-regional location of the remote repository.
• PROJECT_ID with the project ID of the VM.
• REMOTE_REPOSITORY_NAME with the name you gave your remote repository.
• UPSTREAM_REPOSITORY_NAME with the name of the upstream repository for your remote.
• COMPONENTS with a whitespace separated list of component names.

If you create additional Apt repositories, you can add them to the artifact-registry.list or sources.list file and then rerun sudo apt update to update repository sources.

Configure HTTP access to an Apt repository

If using older client tools that don't support SSL encryption, you can configure public access to your Apt repository and access it via HTTP. Requests sent to public readable repositories using HTTP will be rejected if an authentication token is presented with the request.

1. Configure public access to the repository.

2. To configure Apt to fetch packages from your repository using HTTP, run the following command:

    echo 'deb http://LOCATION-apt.pkg.dev/projects/PROJECT_ID \
    REPOSITORY main' | sudo tee -a /etc/apt/sources.list.d/artifact-registry.list
   

   Replace the following:

   • LOCATION with the location of the repository.
   • PROJECT_ID with the project ID of the repository.
   • REPOSITORY with the repository name.

   For example, to install packages from the public repository my-repo in the project my-project and in the location us-central1 using HTTP, use the following command:

   echo 'deb http://us-central1-apt.pkg.dev/projects/my-project my-repo main' | sudo tee -a /etc/apt/sources.list.d/artifact-registry.list
   

3. Update your repository sources with the following command:

   sudo apt update
   

Apt can now connect to the repository.

If you create additional Apt repositories, you can add them to the artifact-registry.list file and then rerun sudo apt update to update repository sources.

What's next

• Learn about managing Debian packages