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
Private repository
Choose the service account you will use to grant access.
- For Compute Engine VMs, this might be the default service account. Artifact Registry automatically retrieves Compute Engine VM service account credentials for any VM using a service account.
- For other VMs, create or choose a service account to act on behalf of your VM. You will need the location of the service account key file to configure the VM. You can view and create keys for existing accounts on the Service Accounts page.
Grant repository access permissions to your service account.
Prepare the VM to access the repository.
Compute Engine VM
Debian VM
Assign
cloud-platform
API access scopes to the VM. For information about setting access scopes, see Changing the service account and access scopes for an instance.Update Apt using the following command:
sudo apt update
Install the
apt-transport-artifact-registry
package on the VM:sudo apt install apt-transport-artifact-registry
Ubuntu VM
Install the Apt repository signing keys, using the following command:
curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add - && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
Replace
LOCATION
with the location of the repository.Assign
cloud-platform
API access scopes to the VM. For information about setting access scopes, see Changing the service account and access scopes for an instance.Configure your VM to access Artifact Registry packages using the following command:
echo 'deb http://packages.cloud.google.com/apt apt-transport-artifact-registry-stable main' | sudo tee -a /etc/apt/sources.list.d/artifact-registry.list
Update Apt using the following command:
sudo apt update
Install the
apt-transport-artifact-registry
package on the VM:sudo apt install apt-transport-artifact-registry
Other VM
Install the Apt repository signing keys, using the following command:
curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add - && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
Replace
LOCATION
with the location of the repository.Configure your VM to access Artifact Registry packages using the following command:
echo 'deb http://packages.cloud.google.com/apt apt-transport-artifact-registry-stable main' | sudo tee -a /etc/apt/sources.list.d/artifact-registry.list
Update Apt using the following command:
sudo apt update
Install the
apt-transport-artifact-registry
package on the VM:sudo apt install apt-transport-artifact-registry
Find the
#Service-Account-JSON "/path/to/creds.json";
line in the/etc/apt/apt.conf.d/90artifact-registry
file, then uncomment the line and add the path of your service account key.Config file entry:
Service-Account-JSON "PATH_TO_SERVICE_ACCOUNT_KEY";
Replace
PATH_TO_SERVICE_ACCOUNT_KEY
with the path to your service account key JSON file.
Public repository
Configure public access to the repository.
If you're configuring a VM outside of Google Cloud, prepare your machine to access the repository. If you're configuring a Compute Engine VM, proceed to the next step.
Install the public signature verification key, using the following command:
curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add -
Replace
LOCATION
with the location of the repository.Update Apt using the following command:
sudo apt update
Configure a VM to access a standard Apt repository
Configure a VM to access an Apt repository:
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
Configure Apt to fetch packages from your repository using the
echo
command from the output of theprint-settings
command.For example, to install packages from the public repository
my-repo
in the projectmy-project
and in the locationus-central1
, use the following command:echo 'deb ar+https://us-central1-apt.pkg.dev/projects/my-project my-repo main'
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.
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
Go to the VM instances page.
In the row with your VM, click SSH.
A new window opens with a terminal session on the VM.
Open the VM's
/etc/apt/sources.list
file and locate the standard repository you want to replace with your new remote repository.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 projectmy-project
in locationus-east1
usingbuster
as the upstream repository for componentsmain
,contrib
, andnon-free
.deb ar+https://us-east1-apt.pkg.dev/remote/my-project/my-repo buster main contrib non-free
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.d
folder,
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.
Configure public access to the repository.
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' >> /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 projectmy-project
and in the locationus-central1
using HTTP, use the following command:echo 'deb http://us-central1-apt.pkg.dev/projects/my-project my-repo main' >> /etc/apt/sources.list.d/artifact-registry.list
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.