diff --git a/explanation/anbox-cloud.md b/explanation/anbox-cloud.md index 36af4fee..644befde 100644 --- a/explanation/anbox-cloud.md +++ b/explanation/anbox-cloud.md @@ -14,7 +14,7 @@ Anbox Cloud comes in two variants that serve different purposes: **Anbox Cloud Appliance** -The Anbox Cloud Appliance is a self-contained deployment variant of Anbox Cloud. It uses a sensible standard configuration to hide the complexity and flexibility of [Juju](https://juju.is/). In this way, the Anbox Cloud Appliance allows simple and fast development and prototyping. +The Anbox Cloud Appliance is a self-contained deployment variant of Anbox Cloud. It combines all elements of Anbox Cloud in a single snap package for installation and management on a single machine. In this way, the Anbox Cloud Appliance allows simple and fast development and prototyping. **Anbox Cloud** diff --git a/howto/anbox/tls-for-appliance.md b/howto/anbox/tls-for-appliance.md index 8fc96ef1..ac9f971c 100644 --- a/howto/anbox/tls-for-appliance.md +++ b/howto/anbox/tls-for-appliance.md @@ -21,14 +21,42 @@ To generate and install a certificate yourself, complete the following steps: Setting up DNS redirection depends on your DNS provider. Refer to the documentation of your provider to create a DNS record pointing to the IP/DNS of the AWS instance where the Anbox Cloud Appliance is running. +```{note} +This option is experimental. It will be removed in a future release when a better replacement exists. +``` + +(ref-appliance-tls-location)= ### Configure the location -Configure the location for the appliance using the created DNS name: +Configure the location for the appliance using the created DNS name. For the following configuration files need to be updated: - sudo snap set anbox-cloud-appliance experimental.location= +#### `/var/snap/anbox-cloud-appliance/common/gateway/config.yaml` -```{note} -This option is experimental. It will be removed in a future release when a better replacement exists. +The configuration file needs to be changed to look as follows + +```yaml +... +endpoint: + address: 192.168.11.195:9031 + public-address: 192.168.11.195 + # Add the location element here if it doesn't exist and set it to your + # DNS name. + location: your.dns.name +... +``` + +#### `/var/snap/anbox-cloud-appliance/common/config.yaml` + +The configuration file needs to be changed to look as follows + +```yaml +log-level: error +listen-address: 192.168.11.195 +location: your.dns.name +... +tls: + # Drop or comment the following line + # ca: /var/snap/anbox-cloud-appliance/common/tls/ca.crt ``` ### Generate an SSL certificate @@ -39,9 +67,9 @@ First, connect and SSH into your appliance instance, and install the `certbot` s sudo snap install --classic certbot -Before generating your certificate using `certbot`, stop the Traefik service from listening on port 80 for the certificate creation: +Before generating your certificate using `certbot`, stop the appliance service from listening on port 80 for the certificate creation: - sudo snap stop anbox-cloud-appliance.traefik + sudo snap stop anbox-cloud-appliance.daemon Then run the following command to generate your certificate: @@ -60,14 +88,14 @@ Certbot has set up a scheduled task to automatically renew this certificate in t ### Install the SSL certificate -Copy the generated certificate to the `/var/snap/anbox-cloud-appliance/common/traefik/tls` directory: +Copy the generated certificate to the `/var/snap/anbox-cloud-appliance/common/daemon` directory: - sudo cp /etc/letsencrypt/live//fullchain.pem /var/snap/anbox-cloud-appliance/common/traefik/tls/cert.pem - sudo cp /etc/letsencrypt/live//privkey.pem /var/snap/anbox-cloud-appliance/common/traefik/tls/key.pem + sudo cp /etc/letsencrypt/live//fullchain.pem /var/snap/anbox-cloud-appliance/common/daemon/server.crt + sudo cp /etc/letsencrypt/live//privkey.pem /var/snap/anbox-cloud-appliance/common/daemon/server.key -Then start the Traefik service: +Then start the appliance service: - sudo snap start anbox-cloud-appliance.traefik + sudo snap start anbox-cloud-appliance.daemon With the certificate installed on the appliance, you now can access the appliance using the created domain name. @@ -75,26 +103,26 @@ With the certificate installed on the appliance, you now can access the applianc The `certbot` snap packages installed on your machine already set up a systemd timer that will automatically renew your certificates before they expire. However, in order to get the certificate renewed successfully for the appliance, you must complete the following steps: -1. Stop the Traefik service to release port 80 right before the certificate is going to be renewed. This can be done through the `pre-hook`: +1. Stop the appliance service to release port 80 right before the certificate is going to be renewed. This can be done through the `pre-hook`: ```bash - cat </fullchain.pem /var/snap/anbox-cloud-appliance/common/traefik/tls/cert.pem - sudo cp /etc/letsencrypt/live//privkey.pem /var/snap/anbox-cloud-appliance/common/traefik/tls/key.pem - sudo snap start anbox-cloud-appliance.traefik + sudo cp /etc/letsencrypt/live//fullchain.pem /var/snap/anbox-cloud-appliance/common/daemon/server.crt + sudo cp /etc/letsencrypt/live//privkey.pem /var/snap/anbox-cloud-appliance/common/daemon/server.key + sudo snap start anbox-cloud-appliance.daemon EOF - sudo chmod +x /etc/letsencrypt/renewal-hooks/post/001-start-traefik.sh + sudo chmod +x /etc/letsencrypt/renewal-hooks/post/001-start-appliance.sh ``` In this way, the SSL certificate auto-renewal is in place. @@ -222,16 +250,7 @@ The following example shows the DNS record with type `A` for the example domain: Finally, configure the Anbox Cloud Appliance to use the domain name that you prepared. 1. Use SSH to connect to the AWS instance where the Anbox Cloud Appliance is running. -1. Run the following command to configure the location of the appliance: - - ``` - sudo snap set anbox-cloud-appliance experimental.location= - ``` -1. Start the `reboot-checker` service to let the core services (for example, the stream gateway) use the new domain name: - - ``` - sudo systemctl start snap.anbox-cloud-appliance.reboot-checker.service - ``` +1. Run the following command to configure the location of the appliance as described in {ref}`ref-appliance-tls-location` You can now use the new domain name to access the Anbox Cloud Appliance. diff --git a/howto/install-appliance/install-on-aws.md b/howto/install-appliance/install-on-aws.md index c5266e3e..545f1563 100644 --- a/howto/install-appliance/install-on-aws.md +++ b/howto/install-appliance/install-on-aws.md @@ -134,12 +134,7 @@ AWS will verify your configuration, subscribe you to the product and launch the ## Access the appliance -When the instance is successfully launched, you can find its public IP address in the instance details page. Use this IP address or the corresponding DNS name to access the status web page. - -By default, the Anbox Cloud Appliance uses self-signed certificates, which might cause a security warning in your browser. Use the mechanism provided by your browser to proceed to the web page. - -![Appliance welcome screen|690x343, 100%](https://assets.ubuntu.com/v1/f35744dc-install_appliance_initialise.png) - +When the instance is successfully launched, you can find its public IP address in the instance details page. Use this IP address or the corresponding DNS name to access the instance over SSH to start the initialisation process. ## Connect to the VM diff --git a/howto/install-appliance/install-on-google-cloud.md b/howto/install-appliance/install-on-google-cloud.md index b7fcd863..36bfc25a 100644 --- a/howto/install-appliance/install-on-google-cloud.md +++ b/howto/install-appliance/install-on-google-cloud.md @@ -71,7 +71,7 @@ Select **Create** to create the virtual machine on Google Cloud. For additional Before installing Anbox Cloud on the virtual machine, you should set up a firewall to control the incoming and outgoing traffic to your virtual machine. From the navigation menu, select **VPC network > Firewall**. Select **Create firewall rule**. -You can create a firewall rule based on your networking requirements following [Google's documentation](https://cloud.google.com/firewall/docs/using-firewalls). The following is an example firewall rule to enable access to the Anbox Cloud Appliance dashboard once the appliance is installed on the virtual machine. +You can create a firewall rule based on your networking requirements following [Google's documentation](https://cloud.google.com/firewall/docs/using-firewalls). The following is an example firewall rule to enable access to the Anbox Cloud Appliance dashboard once the appliance is installed on the virtual machine. ``` Name : anbox-cloud-appliance @@ -87,7 +87,7 @@ Source IPv4 ranges : 0.0.0.0/0 Second source filter : None Destination filter : None Protocols and ports : Specified protocols and ports - TCP ports : 80,443,10000-11000 + TCP ports : 443,10000-11000 UDP ports : 5349,10000-11000,60000-60100 ``` The target tag `foo` will be used as the network tag in the virtual machine settings. This tag should match the network tag of the virtual machine. @@ -98,7 +98,7 @@ Select **Create** to create the firewall rule. ## Connect to the VM -On the virtual machine instance page, connect to the instance using SSH. See [Google's documentation](https://cloud.google.com/compute/docs/ssh-in-browser) for more information. +On the virtual machine instance page, connect to the instance using SSH. See [Google's documentation](https://cloud.google.com/compute/docs/ssh-in-browser) for more information. ## Finish the installation diff --git a/howto/update/upgrade-appliance.md b/howto/update/upgrade-appliance.md index 5040b82a..e57ad6e3 100644 --- a/howto/update/upgrade-appliance.md +++ b/howto/update/upgrade-appliance.md @@ -1,47 +1,4 @@ (howto-upgrade-appliance)= # How to upgrade the Anbox Cloud Appliance -Before you upgrade the Anbox Cloud Appliance, make sure all packages on the machines that are part of the deployment are up-to-date. To do so, run the following commands on each machine: - - sudo apt update - sudo apt upgrade - sudo snap refresh - -The Anbox Cloud Appliance includes an `upgrade` command which will perform all relevant upgrade steps to a newer version of the appliance. First, run `anbox-cloud-appliance status` to check if an update is available: - - status: ready - update-available: true - reboot-needed: false - version: 1.19.0 - -```{important} -While the upgrade process is active, API endpoints and the dashboard will not be available. Anbox Cloud instances will stay active and existing streams will also not be interrupted. -``` - -In the `anbox-cloud-appliance status` command output, the `update-available` field indicates if an update is available. If an update is available, the upgrade process can now be initiated by running the `upgrade` command: - - anbox-cloud-appliance upgrade - -The appliance will now perform all necessary steps to upgrade to the newer available version. - -```{note} -In case automatic updates are disabled for applications, Anbox Management Service (AMS) cannot update the application. See {ref}`sec-configure-automatic-app-updates` to enable automatic updates or to manually update the applications. -``` - -You can watch the upgrade progress on the web interface: - -![Upgrade the appliance|690x435](https://assets.ubuntu.com/v1/1093e239-update_appliance.png) - - or with the same `anbox-cloud-appliance status` command that you used earlier: - - status: maintenance - progress: 40 - update-available: false - reboot-needed: true - version: 1.19.1 - -When the upgrade is successful, the appliance is again available for regular use. - -In case the upgrade fails due to a transient error or an issue with the system configuration, after resolving the issue, use the `--force` option to run the upgrade process again: - - anbox-cloud-appliance upgrade --force +The Anbox Cloud Appliance does not require any specific steps to upgrade other than apply any pending snap package updates. Internally the snap will automatically apply necessary configuration changes and restart servies as needed. \ No newline at end of file diff --git a/images/install_appliance_initialise.png b/images/install_appliance_initialise.png deleted file mode 100644 index 8596a462..00000000 Binary files a/images/install_appliance_initialise.png and /dev/null differ diff --git a/images/install_appliance_status.png b/images/install_appliance_status.png deleted file mode 100644 index a1d8ddd9..00000000 Binary files a/images/install_appliance_status.png and /dev/null differ diff --git a/reference/appliance-preseed.md b/reference/appliance-preseed.md new file mode 100644 index 00000000..8ca2c5b7 --- /dev/null +++ b/reference/appliance-preseed.md @@ -0,0 +1,52 @@ +(ref-appliance-preseed-config)= +# Anbox Cloud Appliance preseed configuration format + +The Anbox Cloud Appliance supports a `--preseed` command line flag for its `init` command that makes it possible to fully configure it in a non-interactive way. + +For example, starting from a clean installation of the Anbox Cloud Appliance, the preseed configuration can be provided in the folowing way: + + cat << EO | sudo anbox-cloud-appliance init --preseed + network: + listen-address: 192.168.11.4 + lxd: + storage-pool: my-pool + project: anbox-cloud + ams: + api: + allowed-uid: [0, 1000] + EOF + +## Configuration format + +The following shows a complete example of the preseed configuration with all available keys: + +```yaml +network: + # An IP address all services the appliance deploys will listen on. + listen-address: 192.168.11.4 + # The IP address the appliance is accessible on when running behind NAT + public-address: 192.168.11.4 + # The DNS name the appliance is accessible on when running behind NAT + public-location: foo.bar +lxd: + # Specifies the path to a storage disk. This can be used to ask the + # appliance to create a new storage pool based on the specified + # storage disk. The option is mutually exclusive to StorageSize + storage-disk: /dev/sdc + # The size in bytes of a new storage pool to create with the name + # specified in `storage-pool`. The option is mutually exclusive to + # `storage-disk` + storage-size: 343413411 + # Specifies the name of an existing LXD storage pool to use. If not + # specified the appliance will automatically select a suitable + # storage pool if available. If `storage-disk` or `storage-size` + # are specified this will describe the name of the storage pool to + # create + storage-pool: local + # The name of a to be created LXD project the appliance will use. If + # not specified the default "anbox-cloud" name will be used. + project: anbox-cloud +ams: + api: + allowed-uids: [0, 1000] +``` \ No newline at end of file diff --git a/reference/cmd-ref/appliance-command-reference/ams.md b/reference/cmd-ref/appliance-command-reference/ams.md deleted file mode 100644 index 4fb53d26..00000000 --- a/reference/cmd-ref/appliance-command-reference/ams.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -orphan: true ---- -# `ams` - -The `ams` command provides access to the Anbox Management Service (AMS) through subcommands. It exposes the AMS HTTPS service on the public endpoint of the machine on which the appliance is running. Using this command, you can expose or unexpose AMS through the load balancer. - - anbox-cloud-appliance ams - -## Subcommands - -The following subcommands are available: - -### `expose` - -Enables access to AMS in the load balancer. - - anbox-cloud-appliance ams expose - -### `unexpose` - -Disables access to AMS in the load balancer. - - anbox-cloud-appliance ams unexpose diff --git a/reference/cmd-ref/appliance-command-reference/dashboard.md b/reference/cmd-ref/appliance-command-reference/dashboard.md index c0c7714e..675c8c38 100644 --- a/reference/cmd-ref/appliance-command-reference/dashboard.md +++ b/reference/cmd-ref/appliance-command-reference/dashboard.md @@ -3,7 +3,7 @@ orphan: true --- # `dashboard` -The `dashboard` command allows access to the web dashboard and also allows you to manage it. By default, the dashboard is enabled and exposed, but you can disable it. You can also register new users for the web dashboard. See {ref}`sec-register-ubuntu-one-appliance` for more information. +The `dashboard` command allows access to the web dashboard and also allows you to manage it. You can register new users for the web dashboard. See {ref}`sec-register-ubuntu-one-appliance` for more information. anbox-cloud-appliance dashboard @@ -11,20 +11,8 @@ The `dashboard` command allows access to the web dashboard and also allows you t The following subcommands are available: -### `expose` - -Enables access to the web dashboard in the load balancer. - - anbox-cloud-appliance dashboard expose - ### `register` Registers a new user for the web dashboard. - anbox-cloud-appliance dashboard register - -### `unexpose` - -Disables access to the web dashboard in the load balancer. - - anbox-cloud-appliance dashboard unexpose + anbox-cloud-appliance dashboard register diff --git a/reference/cmd-ref/appliance-command-reference/destroy.md b/reference/cmd-ref/appliance-command-reference/destroy.md deleted file mode 100644 index 6172a61a..00000000 --- a/reference/cmd-ref/appliance-command-reference/destroy.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -orphan: true ---- -# `destroy` - -The `destroy` command deletes the deployment that the Anbox Cloud Appliance has created on a machine. If you want to uninstall the Anbox Cloud Appliance, you must first run this command before you uninstall the snap. - - anbox-cloud-appliance destroy - -```{caution} -This command resets the Anbox Cloud Appliance and destroys all data. Execution of the command cannot be stopped or reverted. Hence, before destroying a deployment, ensure to backup all necessary data. -``` - -## Options - -`--force` to force the destroy process on non interactive terminals \ No newline at end of file diff --git a/reference/cmd-ref/appliance-command-reference/gateway.md b/reference/cmd-ref/appliance-command-reference/gateway.md deleted file mode 100644 index e1d4f02f..00000000 --- a/reference/cmd-ref/appliance-command-reference/gateway.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -orphan: true ---- -# `gateway` - -The `gateway` command allows and manages access to the HTTP API of the stream gateway. If the HTTP API is exposed (which is the default), authenticated clients can connect to it. - - anbox-cloud-appliance gateway - -## Subcommands - -The following subcommands are available: - -### `account` - -Manages accounts to access the Anbox stream gateway. - - anbox-cloud-appliance gateway account - -The `account` command can be used with two subcommands - `create` and `delete`: - -The `account create` command creates an account to access the Anbox stream gateway. - -This command creates an account with the given and returns a token which you can use for accessing the Anbox Stream Gateway HTTP API directly or through the Anbox Stream SDK. See {ref}`howto-access-stream-gateway` for more information. - - anbox-cloud-appliance gateway account create - -The `account delete` command deletes the specified account and removes access to the Anbox stream gateway for the specified account. - - anbox-cloud-appliance gateway account delete - -### `expose` - -Enables access to the stream gateway in the load balancer. - - anbox-cloud-appliance gateway expose - -### `unexpose` - -Disables access to the stream gateway in the load balancer. - - anbox-cloud-appliance gateway unexpose diff --git a/reference/cmd-ref/appliance-command-reference/init.md b/reference/cmd-ref/appliance-command-reference/init.md index 7d0e2758..3819e2cc 100644 --- a/reference/cmd-ref/appliance-command-reference/init.md +++ b/reference/cmd-ref/appliance-command-reference/init.md @@ -3,7 +3,7 @@ orphan: true --- # `init` -The `init` command configures and initialises the Anbox Cloud Appliance. This command runs through the initial bootstrap process before Anbox Cloud can be used. It provides an interactive configuration dialog which allows you to either accept the defaults or specify custom preferences for configurable aspects of the appliance. +The `init` command configures and initialises the Anbox Cloud Appliance. This command runs through the initial initialization process before Anbox Cloud can be used. It provides an interactive configuration dialog which allows you to either accept the defaults or specify custom preferences for configurable aspects of the appliance. anbox-cloud-appliance init @@ -14,10 +14,5 @@ See {ref}`sec-initialise-appliance` for more information. |Option | Description | |-------|-------------| |`--auto`|To enable automatic (non-interactive) mode. Use this option if you want to accept the default options for the appliance.| -|`--charm-channel `|To specify the store channel from which Anbox Cloud charms are to be deployed. This is an *advanced* option and used mostly for *development purposes*.| -|`--force-network-bridge`|To force using a local network bridge instead of a FAN overlay network| -|`--image-server-auth `|To specify authentication credentials for the Anbox Cloud image server. This is an *advanced* option and used mostly for *development purposes*.| -|`--image-server-url `| To specify the URL of the Anbox Cloud image server. This is an *advanced* option and used mostly for *development purposes*.| |`--preseed`| To enable pre-seed mode, expects YAML config from stdin| -|`--proxy `| To specify the HTTP/HTTPS proxy server to use during installation| -|`--use-existing-gpu-driver`|To indicate that a GPU driver is already installed and ready for use| +|`--force`|Force run, even if already initialized| diff --git a/reference/cmd-ref/appliance-command-reference/landing.md b/reference/cmd-ref/appliance-command-reference/landing.md index 5b522e51..5094fa2f 100644 --- a/reference/cmd-ref/appliance-command-reference/landing.md +++ b/reference/cmd-ref/appliance-command-reference/landing.md @@ -9,13 +9,9 @@ The following commands are available for the `anbox-cloud-appliance` tool: | Command | Description| |---------|------------| -|[`ams`](ams.md) | Manage access to the Anbox Management Service (AMS)| -|[`dashboard`](dashboard.md)| Manage the web dashboard of appliance| -|[`destroy`](destroy.md) | Destroy the appliance| -|[`gateway`](gateway.md) | Manage the appliance stream gateway| |[`help`](help.md) | Help about the `anbox-cloud-appliance` tool| -|[`init`](init.md)| Initialise the appliance| +|[`init`](init.md)| Initialise the Anbox Cloud Appliance| |[`status`](status.md) | Display the current status and version of the appliance| -|[`upgrade`](upgrade.md) | Upgrade the appliance to a newer version| +|[`prepare-node-script`](prepare-node-script.md)| Generate a shell script to prepare a machine for the Anbox Cloud Appliance| If you encounter an issue and want to collect debugging information from the appliance, use `anbox-cloud-appliance.buginfo`. diff --git a/reference/cmd-ref/appliance-command-reference/prepare-node-script.md b/reference/cmd-ref/appliance-command-reference/prepare-node-script.md new file mode 100644 index 00000000..858ca0dd --- /dev/null +++ b/reference/cmd-ref/appliance-command-reference/prepare-node-script.md @@ -0,0 +1,18 @@ +--- +orphan: true +--- +# `prepare-node-script` + +The `prepare-node-script` generates a shell script which needs to be executed outside of the snap execution environment to install additional dependency and adjust system configuration. + +Please carefully review the script before execution! It will install additional kernel modules and GPU drivers and apply configuration changes to tune these for Anbox Cloud. + +You can show the script by running + + $ anbox-cloud-appliance prepare-node-script + +and execute it after reviewing the content by + + $ anbox-cloud-appliance prepare-node-script | sudo bash -ex + +Once the script has finished all preparation is completed. diff --git a/reference/cmd-ref/appliance-command-reference/status.md b/reference/cmd-ref/appliance-command-reference/status.md index e6721565..812c84c6 100644 --- a/reference/cmd-ref/appliance-command-reference/status.md +++ b/reference/cmd-ref/appliance-command-reference/status.md @@ -6,8 +6,6 @@ orphan: true The `status` command displays the following information about the Anbox Cloud Appliance: * Status of the appliance -* If a newer version is available -* If a reboot is required * The current version of the appliance anbox-cloud-appliance status diff --git a/reference/cmd-ref/appliance-command-reference/upgrade.md b/reference/cmd-ref/appliance-command-reference/upgrade.md deleted file mode 100644 index 977b4562..00000000 --- a/reference/cmd-ref/appliance-command-reference/upgrade.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -orphan: true ---- -# `upgrade` - -The `upgrade` command upgrades the Anbox Cloud Appliance to the latest version. During the upgrade process, the appliance temporarily switches to maintenance mode and becomes unavailable until the upgrade is complete. - -See {ref}`howto-upgrade-appliance` for more information. - -## Usage - - anbox-cloud-appliance upgrade