Alpaquita Linux: Getting started with GCP images

1. Overview

BellSoft provides Alpaquita Linux images for the Google Cloud. Alpaquita Linux is an Alpine-based distribution with two libc options (improved musl and glibc) and several performance and security optimizations. Alpaquita cloud images enable developers to build microcontainers and significantly reduce cloud costs.

2. Selecting an image

BellSoft maintains 6 flavors or variations of Alpaquita Linux in GCP:

  • alpaquita-glibc-aarch64

  • alpaquita-glibc-x86-64-bios

  • alpaquita-glibc-x86-64-uefi

  • alpaquita-musl-aarch64

  • alpaquita-musl-x86-64-bios

  • alpaquita-musl-x86-64-uefi

In GCP, these flavors of Alpaquita Linux exist as image families. That means users can create VM instances by specifying a family name and the latest image in the image family will be used to create the VM.

Use BellSoft GCP page to select the GCP OS Images with the combination of parameters that you are interested in.

On the web page you can see all the available images and copy image names.

It is possible to filter the list by the C library implementation (musl or glibc), firmware, and architecture.

In this document we will use the musl C library variant with x86_64 architecture and UEFI firmware.

After filtering the parameters, you can copy the image name by clicking the Copy Image Name button on the right of the filtered entry. After obtaining the image name, you can proceed with creating a VM instance of the Alpaquita image. We will show how to use the gcloud command line interface to achieve that.

3. Creating a VM instance

Important:
This part assumes that you have created a project, enabled Compute Engine API, and completed other required setup. Also, we assume that you have installed and configured gcloud CLI tool. For more information, see gcloud documentation and Compute Engine instances docs

Creating a VM instance using the image name

First lets see how to create an instance using the image name. Use gcloud CLI tool to create an instance as follows:

gcloud compute instances create <instance_name> \
    --project=<your_project>
    --machine-type=<machine_type> \
    --zone=<zone> \
    --image-project=alpaquita-cloud \
    --image=<image_name>

Specify your project name in the --project parameter. For this demo we use alpaquita-public name. Make sure you have a compatible machine type for your image architecture, such as, if you have an aarch64 machine, select aarch64-compatible machine type like c4a for your image in GCP.

See Regions and zones for more information on zones.

--image-project is the project where the image that you are using to create a VM instance is located. All BellSoft Alpaquita Linux images reside in the alpaquita-cloud project.

$ gcloud compute instances create alpq-instance-image-name-demo \
  --project=alpaquita-public \
  --machine-type=e2-micro \
  --zone=us-central1-c \
  --image-project=alpaquita-cloud \
  --image=alpaquita-musl-x86-64-uefi-2025-03-14-16-22


Created [https://www.googleapis.com/compute/v1/projects/alpaquita-public/zones/us-central1-c/instances/alpq-instance-image-name-demo].
NAME                           ZONE           MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP   STATUS
alpq-instance-image-name-demo  us-central1-c  e2-micro                   10.128.0.3   [REDACTED]    RUNNING

As the command output above shows, alpq-instance-image-name-demo instance is created.

After creating the VM using the glcloud CLI, you should be able to see it in GCP web interface:

Although this is a valid method to create an instance, if you want to get the latest image in the image family instead of obtaining the image name manually, GCP provides a better alternative described in the next part.

Creating a VM instance using the image family name

The Alpaquita Linux image names are as follows: <image_family>-<timestamps>. By simply removing the timestamps, you can get the image family.

In automated scripts or in case you want to get the latest image of an image family, gcloud provides a useful option to use image families to create a VM instance:

$ gcloud compute instances create alpq-instance-image-family-demo \
       --image-project=alpaquita-cloud \
       --image-family=alpaquita-musl-x86-64-uefi \
       --project=alpaquita-public
Created [https://www.googleapis.com/compute/v1/projects/alpaquita-public/zones/us-central1-c/instances/alpq-instance-image-family-demo].
NAME                             ZONE           MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP    STATUS
alpq-instance-image-family-demo  us-central1-c  n1-standard-1               10.128.0.7   [REDACTED]     RUNNING

The created instance should appear in the GCP web interface:

4. Logging in to the instance

Log in using browser

If you click the SSH button on your image info page, GCP will connect to your instance by creating an ephemeral SSH key pair for you.

After that you can start using your instance in your browser:

Note:
It is also possible to create you own SSH keys, log in using OSLogin or serial console, and connect to your instance using the gcloud CLI tool. See Connect to Linux VMs document for more information.

5. Viewing logs

Introduction to serial log

GCP’s serial port logs provide an important diagnostic tool for analysis of OS instance boot process. These logs offer insights into various stages of system initialization, making them valuable tool for troubleshooting boot-related issues.

For Alpaquita Linux instances, the serial port logs detailed information from the bootloader, kernel, and hardware initialization systems, among other critical components. By examining these logs, users can identify point of failure or analyze unexpected behavior during the boot sequence.

Logs explorer

Apart from the boot-related logs, the Logs explorer helps you examine the overall statistics, insights, and data about the instance. See the following example.

Click Logging on the instance detail page.

After clicking the link, the Logs explorer opens. The example below highlights the following items.

  1. Using the web interface you can filter the logs in the Logs explorer by the instance ID.

  2. You can adjust the time frame of the logs.

  3. The logs themselves are listed in the lower right part of the page.

As an example, we clicked a log entry that informs about a failed startup script. You can see in-depth information in the log entry such as timestamp, instance name, severity, and so on.

See Startup scripts part for more information about startup scripts.

6. Configuring the VM instance

Startup scripts

The pattern of executing a command during startup of the VM instance is useful for updating the system, installing a software, and so on.

With Alpaquita Linux in GCP it is possible to do that using metadata by web interface or the gcloud CLI tool. We will show how to do it using the web interface.

  1. First, click Edit on the instance details page:

  2. Then write the startup script in the Startup script text field:

    For demonstration purposes, we changed the hostname, wrote a string to the /tmp/hello file, and installed Liberica JDK 21.

    Note:
    You can use other shebang lines for python, perl or any other interpreter.
  3. Stop the instance by clicking Stop on the instance details page:

  4. After re-starting the instance, the startup script should be executed at the later stage of the booting process of the instance.

Let’s verify that the startup script worked as expected:

We can see that the hostname is changed to alpq-startup-script, the /tmp/hello file contains the text we typed, and liberica21 is installed.

Adding a new disk

You can add a separate disk if needed by clicking the Edit button on the instance details page we have used earlier.

  1. Click Add new disk in the Edit section:

  2. Fill in the details, such as disk type, name, size, and region:

  3. After saving the changes in the Edit section, it should be ready to use in the instance:

Other configurations

For more information regarding configuration of Compute Engine instances, see GCP documentation.

ON THIS PAGE