Configuring the APT package manager

This guide describes how to connect the APT package manager (Advanced Package Tool) to a Debian registry in Yandex Cloud Registry.

Preparing a GPG keyPreparing a GPG key

A GPG key is required for a registry with signed metadata. The signature allows clients to verify the authenticity of packages.

1. Generate a GPG key using GnuPG:

   gpg --full-generate-key
   

   When prompted for passphrase, leave this field empty.

2. Retrieve the ID of the GPG key you created:

   gpg --list-secret-keys --keyid-format=long
   

   Result:

   /home/user/.gnupg/secring.gpg
   ------------------------------
   sec   4096R/<GPG_key_ID> 2024-01-01 [expires: 2026-01-01]
   uid                          User Name <user@example.com>
   ssb   4096R/XXXXXXXXXXXXXXXX 2024-01-01
   

3. Export the secret part of the GPG key:

   gpg --armor --export-secret-keys <GPG_key_ID>
   

4. Save the secret part of the GPG key in a Yandex Lockbox secret under the gpg_secret_key_value key:

   yc lockbox secret create \
     --name <secret_name> \
     --payload "[{'key': 'gpg_secret_key_value', 'text_value': '$(gpg --armor --export-secret-keys <GPG_key_ID>)'}]"
   

5. Grant access to the secret contents to the Cloud Registry service agent by assigning it the lockbox.payloadViewer role for this secret:

   yc lockbox secret add-access-binding \
     --id <secret_ID> \
     --role lockbox.payloadViewer \
     --agent cloud-registry:control-plane \
     --cloud-id <cloud_ID>
   

6. Save the public part of the GPG key. Registry users will need this value:

   gpg --armor --export <GPG_key_ID> > public-key.asc
   

Configuring APTConfiguring APT

Local registryLocal registry

1. Add the registry to the APT sources list:

   Registry with signed metadata

   Registry with unsigned metadata

   1. Copy the public GPG key to the directory with APT trusted keys:

      cp /path/to/public-key.asc /usr/share/keyrings/ycr-pub.asc
      

      Where /path/to/public-key.asc is the path to the public GPG key file.

   2. Add the registry to the APT sources list:

      echo "deb [signed-by=/usr/share/keyrings/ycr-pub.asc] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
        >> /etc/apt/sources.list
      

   Add a registry with trusted=yes:

   echo "deb [trusted=yes] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
     >> /etc/apt/sources.list
   

2. Add authentication data to the /etc/apt/auth.conf file:

   IAM token

   API key

   machine https://registry.yandexcloud.net/debian/<registry_ID>
   login iam
   password <IAM_token>
   

   machine https://registry.yandexcloud.net/debian/<registry_ID>
   login api_key
   password <API_key>
   

Remote registryRemote registry

Public sourcePublic source

1. Install the package with the distribution public keys:

   Debian

   Ubuntu

   Run this command:

   sudo apt install debian-archive-keyring
   

   The key will be available at /usr/share/keyrings/debian-archive-keyring.gpg.

   Run this command:

   sudo apt install ubuntu-keyring
   

   The key will be available at /usr/share/keyrings/ubuntu-archive-keyring.gpg.

2. Add the registry to the APT sources list:

   echo "deb [signed-by=<path_to_key>] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
     >> /etc/apt/sources.list
   

   Where:

   • <path_to_key>: Path to the distribution key file, e.g., /usr/share/keyrings/debian-archive-keyring.gpg or /usr/share/keyrings/ubuntu-archive-keyring.gpg.
   • <registry_ID>: Registry ID.
   • <distribution>: Distribution, e.g., bookworm, bullseye, or focal.
   • <component>: Repository component, e.g., main.

3. Add authentication data to the /etc/apt/auth.conf file:

   IAM token

   API key

   machine https://registry.yandexcloud.net/debian/<registry_ID>
   login iam
   password <IAM_token>
   

   machine https://registry.yandexcloud.net/debian/<registry_ID>
   login api_key
   password <API_key>
   

Custom sourceCustom source

1. Add the registry to the APT sources list:

   Source signed with a GPG key

   Source not signed with a GPG key

   1. Save it to the trusted keys directory:

      cp /path/to/upstream-public-key.asc /usr/share/keyrings/upstream-pub.asc
      

      Where /path/to/upstream-public-key.asc is the path to the public key file of the source repository (upstream).

   2. Add the registry to the APT sources list:

      echo "deb [signed-by=/usr/share/keyrings/upstream-pub.asc] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
        >> /etc/apt/sources.list
      

   Specify the trusted=yes parameter for APT to accept unauthenticated packages:

   echo "deb [trusted=yes] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
     >> /etc/apt/sources.list
   

2. Add authentication data to the /etc/apt/auth.conf file:

   IAM token

   API key

   machine https://registry.yandexcloud.net/debian/<registry_ID>
   login iam
   password <IAM_token>
   

   machine https://registry.yandexcloud.net/debian/<registry_ID>
   login api_key
   password <API_key>
   

Useful linksUseful links

• Pushing a Debian package to a registry
• Pulling a Debian package from a registry