Skip to content

EC2: Add additional info on virtualised instances #1404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 29, 2024
Merged

EC2: Add additional info on virtualised instances #1404

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5321f05
EC2: Add config option 'EC2_HYPERVISOR_URI'
viren-nadkarni Jul 25, 2024
3b483ec
Fix typo
viren-nadkarni Jul 25, 2024
b6656fa
Note about only supporting the QEMU driver
viren-nadkarni Jul 25, 2024
4836789
Add workaround for network access to LS from VM
viren-nadkarni Jul 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/en/references/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@ 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 Pro 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) | [Libvirt connection URI](https://libvirt.org/uri.html#remote-uris) that indicates the hypervisor host. Only QEMU drivers are supported at this time. |
| `EC2_MOUNT_BLOCK_DEVICES` | `1`\|`0` (default) | Whether to create and mount user-specified EBS block devices into EC2 container instances. |
| `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)\|`libvirt`\|`mock` | Emulation method to use in LocalStack Pro. This option is not available in LocalStack community. |
Expand Down
31 changes: 28 additions & 3 deletions content/en/user-guide/aws/ec2/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ The execution log is generated at `/var/log/cloud-init-output.log` in the contai
### Networking

{{< callout "note" >}}
Network access to EC2 instance is not possible on macOS.
Network access from host to EC2 instance containers is not possible on macOS.
This is because Docker Desktop on macOS does not expose the bridge network to the host system.
See [Docker Desktop Known Limitations](https://docs.docker.com/desktop/networking/#known-limitations).
{{< /callout >}}
Expand Down Expand Up @@ -426,7 +426,7 @@ 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.
{{< /callout >}}

LocalStack requires the Libvirt socket on the host to be mounted inside the container.
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]({{< ref "installation#starting-localstack-with-docker-compose" >}}), include the following line in `services.localstack.volumes` list:

Expand All @@ -440,8 +440,10 @@ If you are using [Docker CLI]({{< ref "installation#starting-localstack-with-doc
-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`]({{< ref "configuration#ec2" >}}) config option with a connection URI.

The Libvirt VM manager currently does not have full support for persistence.
Underlying virtual machines and volumes are not persisted, instead only their mock respresentations are.
Underlying virtual machines and volumes are not persisted, only their mock respresentations are.

### AMIs

Expand Down Expand Up @@ -543,6 +545,29 @@ You can then use a compatible VNC client (e.g. [TigerVNC](https://tigervnc.org/)
Currently all instances are behind a NAT network.
Instances can access the internet but are inaccessible from the host machine.

It is possible to allow network access to the LocalStack container from within the virtualised 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:

{{< command >}}
$ sudo systemctl restart docker
{{< /command >}}

You can now start the LocalStack container, obtain its IP address and use it from the virtualised instance.

{{< command >}}
$ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' localstack_main
{{< /command >}}

### Elastic Block Stores

LocalStack clones the AMI into an EBS volume when the instance is initialised.
Expand Down