diff --git a/public/images/aws/tiger-vnc.png b/public/images/aws/tiger-vnc.png deleted file mode 100644 index 6e12da1d..00000000 Binary files a/public/images/aws/tiger-vnc.png and /dev/null differ diff --git a/src/content/docs/aws/customization/configuration-options.md b/src/content/docs/aws/customization/configuration-options.md index c8d6420b..d422e86a 100644 --- a/src/content/docs/aws/customization/configuration-options.md +++ b/src/content/docs/aws/customization/configuration-options.md @@ -188,13 +188,9 @@ This section covers configuration options that are specific to certain AWS servi | `EC2_DOCKER_INIT` | `0`\|`1` (default) | Start container instances with docker-init system, learn more [here](https://docs.docker.com/reference/cli/docker/container/run/#init). Disable this if you want to use a custom init system. | | `EC2_DOWNLOAD_DEFAULT_IMAGES` | `0`\|`1` (default) | At startup, LocalStack for AWS downloads latest Ubuntu images from Docker Hub for use as AMIs. This can be disabled for security reasons. | | `EC2_EBS_MAX_VOLUME_SIZE` | `1000` (default) | Maximum size (in MiBs) of user-specified EBS block devices mounted into EC2 container instances. | -| `EC2_HYPERVISOR_URI` | `qemu:///system` (default) | **Deprecated**. [Libvirt connection URI](https://libvirt.org/uri.html#remote-uris) that indicates the hypervisor host. Only QEMU drivers are supported at this time. Used with the deprecated Libvirt VM manager. | -| `EC2_LIBVIRT_NETWORK` | `default` (default) | **Deprecated**. Name of the Libvirt network to use for all instances when using the Libvirt VM manager. | -| `EC2_LIBVIRT_POOL` | `default` (default) | **Deprecated**. Name of the Libvirt storage pool to use for all images when using the Libvirt VM manager. | | `EC2_MOUNT_BLOCK_DEVICES` | `1`\|`0` (default) | Whether to create and mount user-specified EBS block devices into EC2 container instances. | -| `EC2_REFERENCE_DOMAIN` | `my-template-vm` | **Deprecated**. Name of a shut-off Libvirt domain whose configuration will be cloned for all new VMs created by LocalStack. If unset or the domain is not found/not shut-off, LocalStack uses a generic configuration. Used with the deprecated Libvirt VM manager. | | `EC2_REMOVE_CONTAINERS` | `0`\|`1` (default) | Controls whether created Docker containers are removed at instance termination or LocalStack shuts down. Disable this if there is a need to examine the container filesystem for debugging. | -| `EC2_VM_MANAGER` | `docker` (default) \| `kubernetes` (Enterprise) \| `libvirt` (deprecated) \| `mock` | Emulation method to use in LocalStack for AWS. The `kubernetes` value runs instances as Kubernetes pods. The `libvirt` value is **Deprecated** and will be removed in a future release. | +| `EC2_VM_MANAGER` | `docker` (default) \| `kubernetes` (Enterprise) \| `mock` | Emulation method to use in LocalStack for AWS. The `kubernetes` value runs instances as Kubernetes pods. | ### EKS diff --git a/src/content/docs/aws/services/autoscaling.mdx b/src/content/docs/aws/services/autoscaling.mdx index d96e0bcd..d7908ed6 100644 --- a/src/content/docs/aws/services/autoscaling.mdx +++ b/src/content/docs/aws/services/autoscaling.mdx @@ -134,7 +134,7 @@ Replace `i-0d678c4ecf6018dde` with the instance ID that you fetched from the out ## Current Limitations -LocalStack does not support the `docker`/`libvirt` [VM manager for EC2](/aws/services/ec2/#vm-managers). +LocalStack does not support the `docker` [VM manager for EC2](/aws/services/ec2/#vm-managers). It only works with the `mock` VM manager. ## API Coverage diff --git a/src/content/docs/aws/services/ec2.mdx b/src/content/docs/aws/services/ec2.mdx index 60319161..dc144a6c 100644 --- a/src/content/docs/aws/services/ec2.mdx +++ b/src/content/docs/aws/services/ec2.mdx @@ -208,7 +208,11 @@ For advanced setups, LocalStack for AWS comes with emulation capability for cert The underlying method for this can be controlled using the [`EC2_VM_MANAGER`](/aws/customization/configuration-options#ec2) configuration option. You may choose between plain mocked resources, containerized emulation, or the [Kubernetes executor](/aws/customization/kubernetes/kubernetes-executor/#ec2-kubernetes-executor). -Fully virtualized instances via the [Libvirt VM manager](#libvirt-vm-manager) are deprecated and will be removed in a future release. + +:::note +The Libvirt VM manager (`EC2_VM_MANAGER=libvirt`) has been retired and is no longer available. +If you were using it to launch fully virtualized EC2 instances, switch to the [Docker VM manager](#docker-vm-manager). +::: ## Mock VM Manager @@ -455,242 +459,6 @@ Any operation not listed below will use the mock VM manager. | `CreateFleet` | Spawns Docker containers or Kubernetes pods to fulfill fleet capacity requests. Supports On-Demand, Spot, and mixed fleets. | | `DeleteFleets` | Stops and removes the underlying containers or pods when `TerminateInstances` is set to `true`. | -## Libvirt VM Manager - -:::caution[Deprecated] -The Libvirt VM manager is deprecated and will be removed in a future release. -Prefer the [Docker VM manager](#docker-vm-manager) or [Mock VM manager](#mock-vm-manager) instead. -::: - -The Libvirt VM manager uses the [Libvirt](https://libvirt.org/index.html) API to create fully virtualized EC2 resources. -This lets you create EC2 setups which closely resemble AWS EC2. -Currently LocalStack for AWS supports the KVM-accelerated QEMU hypervisor on Linux hosts. - -Installation steps for QEMU/KVM will vary based on the Linux distribution on the host machine. -On Debian/Ubuntu-based distributions, you can run: - -```bash -sudo apt install -y qemu-kvm libvirt-daemon-system -``` - -To check CPU support for virtualization, run: - -``` -kvm-ok -``` - -```bash title="Output" -INFO: /dev/kvm exists -KVM acceleration can be used -``` - -:::tip -You may also need to enable virtualization support at hardware level. -This is often labelled as 'Virtualization Technology', 'VT-d' or 'VT-x' in UEFI/BIOS setups. -::: - -If the Docker host and Libvirt host is the same, the Libvirt socket on the host must be mounted inside the LocalStack container. -This can be done by including the volume mounts when the LocalStack container is started. -If you are using the [Docker Compose template](/aws/getting-started/installation#docker-compose), include the following line in `services.localstack.volumes` list: - -```text -"/var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock" -``` - -If you are using [Docker CLI](/aws/getting-started/installation#docker-cli), include the following parameter in `docker run`: - -```text --v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock -``` - -If you are using a remote Libvirt hypervisor, you can set the [`EC2_HYPERVISOR_URI`](/aws/customization/configuration-options#ec2) config option with a connection URI. - -:::tip -If you encounter an error like `failed to connect to the hypervisor: Permission denied`, you may need to perform additional setup on the hypervisor host. -Please refer to [Libvirt Wiki](https://wiki.libvirt.org/Failed_to_connect_to_the_hypervisor.html#permission-denied) for more details. -::: - -The Libvirt VM manager currently does not have full support for persistence. -Underlying virtual machines and volumes are not persisted, only their mock representations are. - -### AMIs - -All qcow2 images with cloud-init support can be used as AMIs. -You can find the download links for images of popular OSs below. - - - -Canonical provides official Ubuntu images at [cloud-images.ubuntu.com](https://cloud-images.ubuntu.com/). - -Please use the images in qcow2 format ending in `.img`. - - -Debian provides cloud images for direct download at [cdimage.debian.org/cdimage/cloud](http://cdimage.debian.org/cdimage/cloud/). -Please use the `genericcloud` image in qcow2 format. - - - -The Fedora project maintains the official cloud images at [fedoraproject.org/cloud/download](https://fedoraproject.org/cloud/download). - -Please use the qcow2 images. - - -An evaluation version of Windows Server 2012 R2 is provided by [Cloudbase Solutions](https://cloudbase.it/windows-cloud-images/). - - - - -LocalStack does not come preloaded with any AMIs. - -Compatible qcow2 images must be placed in the Libvirt storage pool on the host machine. -By default, this is located at `/var/lib/libvirt/images`. -If you use a different storage pool, configure it using the [`EC2_LIBVIRT_POOL`](/aws/customization/configuration-options#ec2) option. -Images must be named with the prefix `ami-` followed by at least 8 hexadecimal characters without an extension, e.g. `ami-1234abcd`. - -You may need run the following command to make sure the image is registered with Libvirt (replace `default` with your storage pool name if different): - -```bash -virsh pool-refresh default -``` - -```bash title="Output" -Pool default refreshed -``` - -You can then list the images with: - -```bash -virsh vol-list --pool default -``` - -```bash title="Output" - Name Path --------------------------------------------------------------------------------------------------------- - ami-1234abcd /var/lib/libvirt/images/ami-1234abcd -``` - -Only the images that follow the above naming scheme will be recognised by LocalStack as AMIs suitable for launching virtualized instances. -These AMIs will also have the resource tag `ec2_vm_manager:libvirt`. - -```bash -awslocal ec2 describe-images --filters Name=tag:ec2_vm_manager,Values=libvirt -``` - -### Instances - -Virtualized instances can be launched with `RunInstances` operation and specifying a compatible AMI. -LocalStack will create and start a Libvirt domain to represent the instance. - -When instances are launched, LocalStack uses the [NoCloud](https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html) datasource to customize the virtual machine. -The login user is created with the username `localstack` and password `localstack`. -If a key pair is provided, it will added as an authorised SSH key for this user. - -LocalStack shuts down all virtual machines when it terminates. -The Libvirt domains and volumes are left defined and can be used for debugging, etc. - -:::tip -Use [Virtual Machine Manager](https://virt-manager.org/) or [virsh](https://www.libvirt.org/manpages/virsh.html) to manage the virtual machines outside of LocalStack. -::: - -The Libvirt VM manager supports basic shell scripts for user data. -This can be passed to the `UserData` parameter of the `RunInstances` operation. - -To connect to the graphical display of the instance, first obtain the VNC address using: - -```bash -virsh vncdisplay -``` - -```bash title="Output" -127.0.0.1:0 -``` - -You can then use a compatible VNC client (e.g. [TigerVNC](https://tigervnc.org/)) to connect and interact with the virtual machine. - -![Tiger VNC](/images/aws/tiger-vnc.png) - -### Configuration - -The Libvirt VM manager supports several configuration options to customize its behavior. - -#### Domain Cloning - -By default, LocalStack creates VMs using a generic Libvirt domain configuration. -However, certain hypervisor setups may require specialized configurations that LocalStack cannot automatically detect. - -You can use the [`EC2_REFERENCE_DOMAIN`](/aws/customization/configuration-options#ec2) configuration option to specify a pre-configured Libvirt domain that LocalStack will use as a template for all new instances. -LocalStack clones the domain configuration, updating elements like UUID, MAC addresses, and boot volumes as needed. - -To use domain cloning: - -1. Create and configure a Libvirt domain with your desired settings using `virt-manager` or `virsh`. -2. Ensure the domain is in shut-off state. -3. Set `EC2_REFERENCE_DOMAIN` to the domain name when starting LocalStack. - -If the specified domain does not exist or is not in shut-off state, LocalStack falls back to using the generic configuration. - -#### Storage Pool and Network - -By default, LocalStack uses the Libvirt storage pool and network named `default`. -If your Libvirt setup uses different names, you can configure them using: - -- [`EC2_LIBVIRT_POOL`](/aws/customization/configuration-options#ec2): Name of the Libvirt storage pool for images (defaults to `default`). -- [`EC2_LIBVIRT_NETWORK`](/aws/customization/configuration-options#ec2): Name of the Libvirt network for instances (defaults to `default`). - -### Networking - -All instances are assigned interfaces on the configured Libvirt network (see `EC2_LIBVIRT_NETWORK` above). -This makes it possible to have host/instance as well as instance/instance network communication. - -It is possible to allow network access to the LocalStack container from within the virtualized instance. -This is done by configuring the Docker daemon to use the KVM network. -Use the following configuration at `/etc/docker/daemon.json` on the host machine: - -```json -{ - "bridge": "virbr0", - "iptables": false -} -``` - -Then restart the Docker daemon: - -```bash title="Output" -sudo systemctl restart docker -``` - -You can now start the LocalStack container, obtain its IP address and use it from the virtualized instance. - -```bash -docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' localstack_main -``` - -### Elastic Block Stores - -LocalStack clones the AMI into an EBS volume when the instance is initialised. -LocalStack does not resize the instance root volume, instead it inherits the properties of the AMI. - -Currently it is not possible to attach additional EBS volumes to instances. - -### Instance Metadata Service - -The Libvirt VM manager does not support the Instance Metadata Service endpoints. - -### Operations - -The following table explains the emulated action for various API operations. -Any operation not listed below will use the mock VM manager. - -| Operation | Notes | -|:----------------------|:---------------------------------------------------------------------------------------------| -| `DescribeImages` | Returns all mock and Libvirt AMIs | -| `RunInstances` | Defines and starts a Libvirt domain | -| `StartInstances` | Starts an already defined Libvirt domain | -| `StopInstances` | Stops a running Libvirt domain | -| `RebootInstances` | Restarts a Libvirt domain | -| `TerminateInstances` | Stops and undefines a Libvirt domain | -| `CreateVolume` | Creates a sparse Libvirt volume | - ## IAM Condition Keys When [IAM Policy Enforcement](/aws/developer-tools/security-testing/iam-policy-enforcement/) is enabled, LocalStack supports the following EC2-specific condition keys, matching the behavior described in the [AWS condition keys reference](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonec2.html#amazonec2-policy-keys):