diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt new file mode 100644 index 00000000..7446f774 --- /dev/null +++ b/.custom_wordlist.txt @@ -0,0 +1,326 @@ +AAM +AAOS +AAPT +AAR +AArch +ABI +ABIs +ACLs +ADB +addon +addons +allocator +Altra +AMC +amd +AMI +AMS +Anbox +anbox +anonymization +ANR +anv +AOSP +APIs +APK +APK's +APKs +AppArmor +Appium +ARMv +async +AttributeError +AudioTrack +backend +balancer +balancers +bbr +benchmarking +binderfs +bitrate +bitrates +Biometrics +Bluetooth +BombSquad +bool +boolean +BPF +bzip +CDN +Center +CFS +cgroup +cgroup-v1 +cgroup-v2 +config +conformant +Charmhub +Charmstore +CLI +CloudFront +codec +codecs +Coturn +CPUs +crashdump +Crashpad +CSV +CTS +CUDA +customisable +customisation +customisations +CustomLocale +datacenter +dataset +deallocate +deallocated +DDoS +Debian +deprecations +Dev +devmode +DNS +dnsmasq +Dqlite +DrArm +drawio +DRM +easyrsa +Easy-RSA +EBS +EFI +EFS +EGL +EINVAL +EmuGL +EOL +ERD +ETag +etcd +executables +favicon +FEC +ffmpeg +FormatException +frontend +fullscreen +gamepad +gameplay +GL +Golang +GPG +GPUs +Grafana +Graviton +gRPC +HAProxy +HIDL +Honkai +hotfix +HTTPS +HW +HWE +HVAC +IAM +idmapped +IDR +IME +impactful +Intra +IoT +IPC +IPs +iptables +init +interprocess +iOS +Javascript +Jira +jitter +JS +JSON +Juju +Juju's +kb +keybinding +KeyError +Keystore +KSM +Lawnchair +Libsoup +libwayland +Linux +linux +Livepatch +LLVMpipe +LMA +localhost +LTS +LXC +LXD +MAAS +macOS +middleware +Minetest +monospaced +mutex +NACK +namespace +natively +NATs +netlink +NewPipe +NFS +NIC +NMEA +NRPE +nrpe +null +NUMA +numpad +NvEnc +NVIDIA +NVMe +OAuth +OBB +OBD +observability +ODM +OES +OOB +OOM +OpenAPI +OpenGL +OpenStack +PCI +Perfetto +PKI +playout +Plex +PLI +powershell +pre +preselected +Quickstart +quickstart +radv +Rasterization +rasterization +RDNA +rc +README +rebased +RenderDoc +Renderdoc +renderdoc +renderer +RenderThread +RESTful +RFE +RGBA +roadmap +RootFS +RSA +rsa +RTC +RTP +RTT +runtime +scalable +scalability +schedulable +scrcpy +SDK +SDKs +SEGV +SELinux +sendfile +SensorManager +SHA +shader +shiftfs +SIGBUS +signaling +simplestreams +SkiaPipeline +SLI +Snapcraft +snapd +spammy +SSD +SSL +SSO +SSRC +stderr +stdin +stdout +subcluster +subclusters +subcommand +subcommands +subnet +subnets +SurfaceFlinger +swiftshader +swrast +syscall +syscalls +systemd +telegraf +tryCapture +TCP +Telegraf +Tensorflow +TLS +Traefik +TypeError +UA +UDA +UDP +UI +unencrypted +unexpose +unhandled +unschedulable +untrusted +uptime +userspace +UTF +validator +vCPU +vCPUs +VHAL +vhal +VhalConnector +VhalPropertyStatus +VirGL +virglrenderer +VM +VMs +VNC +VNDK +VPC +VPN +VPU +VPUs +vsync +Vulkan +vsync +Wayland +WebGL +WebRTC +WebSocket +websocket +websockets +WebView +WiFi +WGS +workspaces +WX +xz +YAML +ZFS +zpool +Uber +upscaling \ No newline at end of file diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml new file mode 100644 index 00000000..a6eb0ab7 --- /dev/null +++ b/.github/workflows/automatic-doc-checks.yml @@ -0,0 +1,16 @@ +name: Main Documentation Checks + +on: + - push + - pull_request + - workflow_dispatch + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + documentation-checks: + uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main + with: + working-directory: '.' \ No newline at end of file diff --git a/.github/workflows/do-not-edit.yml b/.github/workflows/do-not-edit.yml deleted file mode 100644 index 6ff786b6..00000000 --- a/.github/workflows/do-not-edit.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: Check for files that should not be edited - -on: - push: - branches-ignore: - - main - paths: - - 'reference/ams-configuration.md' - pull_request: - paths: - - 'reference/ams-configuration.md' - -jobs: - check: - name: Fail - runs-on: ubuntu-latest - steps: - - name: Print error - run: echo "::error file=reference/ams-configuration.md::Never edit reference/ams-configuration.md manually - edit reference/ams-configuration.tmpl.md or reference/ams-configuration.yaml instead!" - - - name: Exit - run: exit 1 diff --git a/.github/workflows/docs-links.yml b/.github/workflows/docs-links.yml deleted file mode 100644 index 40491946..00000000 --- a/.github/workflows/docs-links.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: Check for links pointing to Anbox docs - -on: - - push - - pull_request - -jobs: - check: - name: Check docs links - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - name: Get changed files - id: changed-files - uses: tj-actions/changed-files@v44 - with: - files_ignore: | - .github - reference/release-notes - - - name: Find Anbox Cloud docs links - id: find-anbox-cloud-docs-links - run: | - awk '{ - # Use match explicitly to have access to retrieve column numbers - # with RSTART and RLENGTH - if (match($0, "anbox-cloud.io/docs") != 0) - print "::error file="FILENAME\ - ",line="FNR\ - ",col="RSTART\ - ",endColumn="RSTART+RLENGTH\ - ",title=Incorrect docs link"\ - "::Documentation links should point to Discourse" - }' ${{ steps.changed-files.outputs.all_changed_files }} diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml deleted file mode 100644 index 5fe3955f..00000000 --- a/.github/workflows/generate.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: Generate and commit AMS configuration doc - -on: - push: - paths: - - 'reference/ams-configuration.tmpl.md' - - 'reference/ams-configuration.yaml' - pull_request: - paths: - - 'reference/ams-configuration.tmpl.md' - - 'reference/ams-configuration.yaml' - -jobs: - generate: - name: Generate and (maybe) commit - runs-on: ubuntu-latest - steps: - - name: Checkout repo - uses: actions/checkout@v4 - - - name: Generate Markdown file - run: python scripts/generate-ams-config.py - - - name: Show Markdown file - run: cat reference/ams-configuration.md - - - name: Commit changes - if: ${{ github.ref == 'refs/heads/main' }} - uses: EndBug/add-and-commit@v9 - with: - default_author: github_actions - message: 'Generate AMS configuration doc' - add: 'reference/ams-configuration.md' diff --git a/.github/workflows/spelling.yml b/.github/workflows/spelling.yml deleted file mode 100644 index 169e6e5c..00000000 --- a/.github/workflows/spelling.yml +++ /dev/null @@ -1,25 +0,0 @@ -name: spellcheck - -on: - - push - - pull_request - -jobs: - spelling: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Set up Python 3.7 - uses: actions/setup-python@v5 - with: - python-version: 3.7 - - name: Install dependencies - run: | - python -m pip install --upgrade pip setuptools - python -m pip install pyspelling - - name: Install Aspell - run: | - sudo apt-get install aspell aspell-en - - name: Spell check - run: | - python -m pyspelling -c .spellcheck.yaml diff --git a/.github/workflows/woke.yml b/.github/workflows/woke.yml deleted file mode 100644 index 0fb2d184..00000000 --- a/.github/workflows/woke.yml +++ /dev/null @@ -1,20 +0,0 @@ -name: Inclusive naming check - -on: - - push - - pull_request - -jobs: - woke: - name: woke - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: woke - uses: get-woke/woke-action@v0 - with: - # Cause the check to fail on any broke rules - fail-on-error: true - woke-args: "*.md **/*.md -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml" diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..d35f4649 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,30 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + jobs: + post_checkout: + - python3 build_requirements.py + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: conf.py + fail_on_warning: false + +# If using Sphinx, optionally build your docs in additional formats such as PDF +formats: + - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: .sphinx/requirements.txt diff --git a/.spellcheck.yaml b/.spellcheck.yaml deleted file mode 100644 index 30a3abc4..00000000 --- a/.spellcheck.yaml +++ /dev/null @@ -1,25 +0,0 @@ -matrix: -- name: Markdown files - aspell: - lang: en - d: en_GB - dictionary: - wordlists: - - .wordlist.txt - output: .wordlist.dic - sources: - - ./**/*.md|!./index.md - pipeline: - - pyspelling.filters.markdown: - markdown_extensions: - - markdown.extensions.fenced_code - - markdown.extensions.admonition - - pyspelling.filters.url: - - pyspelling.filters.html: - comments: false - attributes: - - title - - alt - ignores: - - code - - pre \ No newline at end of file diff --git a/.sphinx/_static/custom.css b/.sphinx/_static/custom.css new file mode 100644 index 00000000..15f27823 --- /dev/null +++ b/.sphinx/_static/custom.css @@ -0,0 +1,349 @@ +/** + Ubuntu variable font definitions. + Based on https://github.com/canonical/vanilla-framework/blob/main/scss/_base_fontfaces.scss + + When font files are updated in Vanilla, the links to font files will need to be updated here as well. +*/ + +/* default font set */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/f1ea362b-Ubuntu%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations'); +} + +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: italic; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/90b59210-Ubuntu-Italic%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations'); +} + +@font-face { + font-family: 'Ubuntu Mono variable'; + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/d5fc1819-UbuntuMono%5Bwght%5D-latin-v0.869.woff2') format('woff2-variations'); +} + +/* cyrillic-ext */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/77cd6650-Ubuntu%5Bwdth,wght%5D-cyrillic-extended-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0460-052F, U+20B4, U+2DE0-2DFF, U+A640-A69F; +} + +/* cyrillic */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/2702fce5-Ubuntu%5Bwdth,wght%5D-cyrillic-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} + +/* greek-ext */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/5c108b7d-Ubuntu%5Bwdth,wght%5D-greek-extended-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+1F00-1FFF; +} + +/* greek */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/0a14c405-Ubuntu%5Bwdth,wght%5D-greek-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0370-03FF; +} + +/* latin-ext */ +@font-face { + font-family: 'Ubuntu variable'; + font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */ + font-style: normal; + font-weight: 100 800; /* min and max value for the weight axis */ + src: url('https://assets.ubuntu.com/v1/19f68eeb-Ubuntu%5Bwdth,wght%5D-latin-extended-v0.896a.woff2') format('woff2-variations'); + unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF; +} + + +/** Define font-weights as per Vanilla + Based on: https://github.com/canonical/vanilla-framework/blob/main/scss/_base_typography-definitions.scss + + regular text: 400, + bold: 550, + thin: 300, + + h1: bold, + h2: 180; + h3: bold, + h4: 275, + h5: bold, + h6: regular +*/ + +/* default regular text */ +html { + font-weight: 400; +} + +/* heading specific definitions */ +h1, h3, h5 { font-weight: 550; } +h2 { font-weight: 180; } +h4 { font-weight: 275; } + +/* bold */ +.toc-tree li.scroll-current>.reference, +dl.glossary dt, +dl.simple dt, +dl:not([class]) dt { + font-weight: 550; +} + + +/** Table styling **/ + +th.head { + text-transform: uppercase; + font-size: var(--font-size--small); + text-align: initial; +} + +table.align-center th.head { + text-align: center +} + +table.docutils { + border: 0; + box-shadow: none; + width:100%; +} + +table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child { + border-right: none; + border-left: none; +} + +/* Allow to centre text horizontally in table data cells */ +table.align-center { + text-align: center !important; +} + +/** No rounded corners **/ + +.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight { + border-radius: 0; +} + +/** Admonition styling **/ + +.admonition { + border-top: 1px solid #d9d9d9; + border-right: 1px solid #d9d9d9; + border-bottom: 1px solid #d9d9d9; +} + +/** Color for the "copy link" symbol next to headings **/ + +a.headerlink { + color: var(--color-brand-primary); +} + +/** Line to the left of the current navigation entry **/ + +.sidebar-tree li.current-page { + border-left: 2px solid var(--color-brand-primary); +} + +/** Some tweaks for Sphinx tabs **/ + +[role="tablist"] { + border-bottom: 1px solid var(--color-sidebar-item-background--hover); +} + +.sphinx-tabs-tab[aria-selected="true"], .sd-tab-set>input:checked+label{ + border: 0; + border-bottom: 2px solid var(--color-brand-primary); + font-weight: 400; + font-size: 1rem; + color: var(--color-brand-primary); +} + +body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] { + background: var(--color-background-primary); + border-bottom: 2px solid var(--color-brand-primary); +} + +button.sphinx-tabs-tab[aria-selected="false"]:hover, .sd-tab-set>input:not(:checked)+label:hover { + border-bottom: 2px solid var(--color-foreground-border); +} + +button.sphinx-tabs-tab[aria-selected="false"]{ + border-bottom: 2px solid var(--color-background-primary); +} + +body[data-theme="dark"] .sphinx-tabs-tab { + background: var(--color-background-primary); +} + +.sphinx-tabs-tab, .sd-tab-set>label{ + color: var(--color-brand-primary); + font-family: var(--font-stack); + font-weight: 400; + font-size: 1rem; + padding: 1em 1.25em .5em +} + +.sphinx-tabs-panel { + border: 0; + border-bottom: 1px solid var(--color-sidebar-item-background--hover); + background: var(--color-background-primary); + padding: 0.75rem 0 0.75rem 0; +} + +body[data-theme="dark"] .sphinx-tabs-panel { + background: var(--color-background-primary); +} + +/** Custom classes to fix scrolling in tables by decreasing the + font size or breaking certain columns. + Specify the classes in the Markdown file with, for example: + ```{rst-class} break-col-4 min-width-4-8 + ``` +**/ + +table.dec-font-size { + font-size: smaller; +} +table.break-col-1 td.text-left:first-child { + word-break: break-word; +} +table.break-col-4 td.text-left:nth-child(4) { + word-break: break-word; +} +table.min-width-1-15 td.text-left:first-child { + min-width: 15em; +} +table.min-width-4-8 td.text-left:nth-child(4) { + min-width: 8em; +} + +/** Underline for abbreviations **/ + +abbr[title] { + text-decoration: underline solid #cdcdcd; +} + +/** Use the same style for right-details as for left-details **/ +.bottom-of-page .right-details { + font-size: var(--font-size--small); + display: block; +} + +/** Version switcher */ +button.version_select { + color: var(--color-foreground-primary); + background-color: var(--color-toc-background); + padding: 5px 10px; + border: none; +} + +.version_select:hover, .version_select:focus { + background-color: var(--color-sidebar-item-background--hover); +} + +.version_dropdown { + position: relative; + display: inline-block; + text-align: right; + font-size: var(--sidebar-item-font-size); +} + +.available_versions { + display: none; + position: absolute; + right: 0px; + background-color: var(--color-toc-background); + box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); + z-index: 11; +} + +.available_versions a { + color: var(--color-foreground-primary); + padding: 12px 16px; + text-decoration: none; + display: block; +} + +.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)} + +.show {display:block;} + +/** Fix for nested numbered list - the nested list is lettered **/ +ol.arabic ol.arabic { + list-style: lower-alpha; +} + +/** Make expandable sections look like links **/ +details summary { + color: var(--color-link); +} + +/** Fix the styling of the version box for readthedocs **/ + +#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version { + background: var(--color-sidebar-item-background--hover); +} + +.rst-versions .rst-other-versions dd a { + color: var(--color-link); +} + +#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions { + color: var(--color-sidebar-link-text); +} + +.rst-versions .rst-current-version { + color: var(--color-version-popup); + font-weight: bolder; +} + +/* Code-block copybutton invisible by default + (overriding Furo config to achieve default copybutton setting). */ +.highlight button.copybtn { + opacity: 0; +} + +/* Mimicking the 'Give feedback' button for UX consistency */ +.sidebar-search-container input[type=submit] { + color: #FFFFFF; + border: 2px solid #D6410D; + padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal); + background: #D6410D; + font-weight: bold; + font-size: var(--font-size--small); + cursor: pointer; +} + +.sidebar-search-container input[type=submit]:hover { + text-decoration: underline; +} + +/* Make inline code the same size as code blocks */ +p code.literal { + border: 0; + font-size: var(--code-font-size); +} diff --git a/.sphinx/_static/favicon.png b/.sphinx/_static/favicon.png new file mode 100644 index 00000000..7f175e46 Binary files /dev/null and b/.sphinx/_static/favicon.png differ diff --git a/.sphinx/_static/furo_colors.css b/.sphinx/_static/furo_colors.css new file mode 100644 index 00000000..422c777d --- /dev/null +++ b/.sphinx/_static/furo_colors.css @@ -0,0 +1,89 @@ +body { + --color-code-background: #f8f8f8; + --color-code-foreground: black; + --code-font-size: 1rem; + --font-stack: Ubuntu variable, Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif; + --font-stack--monospace: Ubuntu Mono variable, Ubuntu Mono, Consolas, Monaco, Courier, monospace; + --color-foreground-primary: #111; + --color-foreground-secondary: var(--color-foreground-primary); + --color-foreground-muted: #333; + --color-background-secondary: #FFF; + --color-background-hover: #f2f2f2; + --color-brand-primary: #111; + --color-brand-content: #06C; + --color-api-background: #cdcdcd; + --color-inline-code-background: rgba(0,0,0,.03); + --color-sidebar-link-text: #111; + --color-sidebar-item-background--current: #ebebeb; + --color-sidebar-item-background--hover: #f2f2f2; + --toc-font-size: var(--font-size--small); + --color-admonition-title-background--note: var(--color-background-primary); + --color-admonition-title-background--tip: var(--color-background-primary); + --color-admonition-title-background--important: var(--color-background-primary); + --color-admonition-title-background--caution: var(--color-background-primary); + --color-admonition-title--note: #24598F; + --color-admonition-title--tip: #24598F; + --color-admonition-title--important: #C7162B; + --color-admonition-title--caution: #F99B11; + --color-highlighted-background: #EbEbEb; + --color-link-underline: var(--color-background-primary); + --color-link-underline--hover: var(--color-background-primary); + --color-version-popup: #772953; +} + +@media not print { + body[data-theme="dark"] { + --color-code-background: #202020; + --color-code-foreground: #d0d0d0; + --color-foreground-secondary: var(--color-foreground-primary); + --color-foreground-muted: #CDCDCD; + --color-background-secondary: var(--color-background-primary); + --color-background-hover: #666; + --color-brand-primary: #fff; + --color-brand-content: #06C; + --color-sidebar-link-text: #f7f7f7; + --color-sidebar-item-background--current: #666; + --color-sidebar-item-background--hover: #333; + --color-admonition-background: transparent; + --color-admonition-title-background--note: var(--color-background-primary); + --color-admonition-title-background--tip: var(--color-background-primary); + --color-admonition-title-background--important: var(--color-background-primary); + --color-admonition-title-background--caution: var(--color-background-primary); + --color-admonition-title--note: #24598F; + --color-admonition-title--tip: #24598F; + --color-admonition-title--important: #C7162B; + --color-admonition-title--caution: #F99B11; + --color-highlighted-background: #666; + --color-link-underline: var(--color-background-primary); + --color-link-underline--hover: var(--color-background-primary); + --color-version-popup: #F29879; + } + @media (prefers-color-scheme: dark) { + body:not([data-theme="light"]) { + --color-code-background: #202020; + --color-code-foreground: #d0d0d0; + --color-foreground-secondary: var(--color-foreground-primary); + --color-foreground-muted: #CDCDCD; + --color-background-secondary: var(--color-background-primary); + --color-background-hover: #666; + --color-brand-primary: #fff; + --color-brand-content: #06C; + --color-sidebar-link-text: #f7f7f7; + --color-sidebar-item-background--current: #666; + --color-sidebar-item-background--hover: #333; + --color-admonition-background: transparent; + --color-admonition-title-background--note: var(--color-background-primary); + --color-admonition-title-background--tip: var(--color-background-primary); + --color-admonition-title-background--important: var(--color-background-primary); + --color-admonition-title-background--caution: var(--color-background-primary); + --color-admonition-title--note: #24598F; + --color-admonition-title--tip: #24598F; + --color-admonition-title--important: #C7162B; + --color-admonition-title--caution: #F99B11; + --color-highlighted-background: #666; + --color-link-underline: var(--color-background-primary); + --color-link-underline--hover: var(--color-background-primary); + --color-version-popup: #F29879; + } + } +} diff --git a/.sphinx/_static/github_issue_links.css b/.sphinx/_static/github_issue_links.css new file mode 100644 index 00000000..db166ed9 --- /dev/null +++ b/.sphinx/_static/github_issue_links.css @@ -0,0 +1,24 @@ +.github-issue-link-container { + padding-right: 0.5rem; +} +.github-issue-link { + font-size: var(--font-size--small); + font-weight: bold; + background-color: #D6410D; + padding: 13px 23px; + text-decoration: none; +} +.github-issue-link:link { + color: #FFFFFF; +} +.github-issue-link:visited { + color: #FFFFFF +} +.muted-link.github-issue-link:hover { + color: #FFFFFF; + text-decoration: underline; +} +.github-issue-link:active { + color: #FFFFFF; + text-decoration: underline; +} diff --git a/.sphinx/_static/github_issue_links.js b/.sphinx/_static/github_issue_links.js new file mode 100644 index 00000000..f0706038 --- /dev/null +++ b/.sphinx/_static/github_issue_links.js @@ -0,0 +1,34 @@ +// if we already have an onload function, save that one +var prev_handler = window.onload; + +window.onload = function() { + // call the previous onload function + if (prev_handler) { + prev_handler(); + } + + const link = document.createElement("a"); + link.classList.add("muted-link"); + link.classList.add("github-issue-link"); + link.text = "Give feedback"; + link.href = ( + github_url + + "/issues/new?" + + "title=docs%3A+TYPE+YOUR+QUESTION+HERE" + + "&body=*Please describe the question or issue you're facing with " + + `"${document.title}"` + + ".*" + + "%0A%0A%0A%0A%0A" + + "---" + + "%0A" + + `*Reported+from%3A+${location.href}*` + ); + link.target = "_blank"; + + const div = document.createElement("div"); + div.classList.add("github-issue-link-container"); + div.append(link) + + const container = document.querySelector(".article-container > .content-icon-container"); + container.prepend(div); +}; diff --git a/.sphinx/_static/header-nav.js b/.sphinx/_static/header-nav.js new file mode 100644 index 00000000..3608576e --- /dev/null +++ b/.sphinx/_static/header-nav.js @@ -0,0 +1,10 @@ +$(document).ready(function() { + $(document).on("click", function () { + $(".more-links-dropdown").hide(); + }); + + $('.nav-more-links').click(function(event) { + $('.more-links-dropdown').toggle(); + event.stopPropagation(); + }); +}) diff --git a/.sphinx/_static/header.css b/.sphinx/_static/header.css new file mode 100644 index 00000000..0b944090 --- /dev/null +++ b/.sphinx/_static/header.css @@ -0,0 +1,167 @@ +.p-navigation { + border-bottom: 1px solid var(--color-sidebar-background-border); +} + +.p-navigation__nav { + background: #333333; + display: flex; +} + +.p-logo { + display: flex !important; + padding-top: 0 !important; + text-decoration: none; +} + +.p-logo-image { + height: 44px; + padding-right: 10px; +} + +.p-logo-text { + margin-top: 18px; + color: white; + text-decoration: none; +} + +ul.p-navigation__links { + display: flex; + list-style: none; + margin-left: 0; + margin-top: auto; + margin-bottom: auto; + max-width: 800px; + width: 100%; +} + +ul.p-navigation__links li { + margin: 0 auto; + text-align: center; + width: 100%; +} + +ul.p-navigation__links li a { + background-color: rgba(0, 0, 0, 0); + border: none; + border-radius: 0; + color: var(--color-sidebar-link-text); + display: block; + font-weight: 400; + line-height: 1.5rem; + margin: 0; + overflow: hidden; + padding: 1rem 0; + position: relative; + text-align: left; + text-overflow: ellipsis; + transition-duration: .1s; + transition-property: background-color, color, opacity; + transition-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1); + white-space: nowrap; + width: 100%; +} + +ul.p-navigation__links .p-navigation__link { + color: #ffffff; + font-weight: 300; + text-align: center; + text-decoration: none; +} + +ul.p-navigation__links .p-navigation__link:hover { + background-color: #2b2b2b; +} + +ul.p-navigation__links .p-dropdown__link:hover { + background-color: var(--color-sidebar-item-background--hover); +} + +ul.p-navigation__links .p-navigation__sub-link { + background: var(--color-background-primary); + padding: .5rem 0 .5rem .5rem; + font-weight: 300; +} + +ul.p-navigation__links .more-links-dropdown li a { + border-left: 1px solid var(--color-sidebar-background-border); + border-right: 1px solid var(--color-sidebar-background-border); +} + +ul.p-navigation__links .more-links-dropdown li:first-child a { + border-top: 1px solid var(--color-sidebar-background-border); +} + +ul.p-navigation__links .more-links-dropdown li:last-child a { + border-bottom: 1px solid var(--color-sidebar-background-border); +} + +ul.p-navigation__links .p-navigation__logo { + padding: 0.5rem; +} + +ul.p-navigation__links .p-navigation__logo img { + width: 40px; +} + +ul.more-links-dropdown { + display: none; + overflow-x: visible; + height: 0; + z-index: 55; + padding: 0; + position: relative; + list-style: none; + margin-bottom: 0; + margin-top: 0; +} + +.nav-more-links::after { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath fill='%23111' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/%3E%3C/svg%3E"); + background-position: center; + background-repeat: no-repeat; + background-size: contain; + content: ""; + display: block; + filter: invert(100%); + height: 1rem; + pointer-events: none; + position: absolute; + right: 1rem; + text-indent: calc(100% + 10rem); + top: calc(1rem + 0.25rem); + width: 1rem; +} + +.nav-ubuntu-com { + display: none; +} + +@media only screen and (min-width: 480px) { + ul.p-navigation__links li { + width: 100%; + } + + .nav-ubuntu-com { + display: inherit; + } +} + +@media only screen and (max-width: 800px) { + .nav-more-links { + margin-left: auto !important; + padding-right: 2rem !important; + width: 8rem !important; + } +} + +@media only screen and (min-width: 800px) { + ul.p-navigation__links li { + width: 100% !important; + } +} + +@media only screen and (min-width: 1310px) { + ul.p-navigation__links { + margin-left: calc(50% - 41em); + } +} diff --git a/.sphinx/_static/tag.png b/.sphinx/_static/tag.png new file mode 100644 index 00000000..f6f6e5aa Binary files /dev/null and b/.sphinx/_static/tag.png differ diff --git a/.sphinx/_templates/base.html b/.sphinx/_templates/base.html new file mode 100644 index 00000000..33081547 --- /dev/null +++ b/.sphinx/_templates/base.html @@ -0,0 +1,12 @@ +{% extends "furo/base.html" %} + +{% block theme_scripts %} + +{% endblock theme_scripts %} + +{# ru-fu: don't include the color variables from the conf.py file, but use a + separate CSS file to save space #} +{% block theme_styles %} +{% endblock theme_styles %} diff --git a/.sphinx/_templates/footer.html b/.sphinx/_templates/footer.html new file mode 100644 index 00000000..bf320c1b --- /dev/null +++ b/.sphinx/_templates/footer.html @@ -0,0 +1,105 @@ +{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #} + +
+ {# mod: Per-page navigation #} + {% if meta %} + {% if 'sequential_nav' in meta %} + {% set sequential_nav = meta.sequential_nav %} + {% endif %} + {% endif %} + {# mod: Conditional wrappers to control page navigation buttons #} + {% if sequential_nav != "none" -%} + {% if next and (sequential_nav == "next" or sequential_nav == "both") -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(root_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} + Copyright © {{ copyright }} + {%- endtrans %} + {%- endif %} +
+ {%- endif %} + + {# mod: removed "Made with" #} + + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} + + {%- if show_source and has_source and sourcename %} +
+ Show source +
+ {%- endif %} +
+
+ + {# mod: replaced RTD icons with our links #} + + {% if discourse %} +
+ Ask a question on Discourse +
+ {% endif %} + + {% if mattermost %} +
+ Ask a question on Mattermost +
+ {% endif %} + + {% if github_url and github_version and github_folder %} + + {% if github_issues %} +
+ Open a GitHub issue for this page +
+ {% endif %} + +
+ Edit this page on GitHub +
+ {% endif %} + + +
+
+ diff --git a/.sphinx/_templates/header.html b/.sphinx/_templates/header.html new file mode 100644 index 00000000..1a128b6f --- /dev/null +++ b/.sphinx/_templates/header.html @@ -0,0 +1,36 @@ + diff --git a/.sphinx/_templates/page.html b/.sphinx/_templates/page.html new file mode 100644 index 00000000..bda30610 --- /dev/null +++ b/.sphinx/_templates/page.html @@ -0,0 +1,49 @@ +{% extends "furo/page.html" %} + +{% block footer %} + {% include "footer.html" %} +{% endblock footer %} + +{% block body -%} + {% include "header.html" %} + {{ super() }} +{%- endblock body %} + +{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} + {% set furo_hide_toc_orig = furo_hide_toc %} + {% set furo_hide_toc=false %} +{% endif %} + +{% block right_sidebar %} +
+ {% if not furo_hide_toc_orig %} +
+ + {{ _("Contents") }} + +
+
+
+ {{ toc }} +
+
+ {% endif %} + {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} +
+ + Related links + +
+
+
+ {% if meta.discourse and discourse_prefix %} + {{ discourse_links(meta.discourse) }} + {% endif %} + {% if meta.relatedlinks %} + {{ related_links(meta.relatedlinks) }} + {% endif %} +
+
+ {% endif %} +
+{% endblock right_sidebar %} diff --git a/.sphinx/_templates/sidebar/search.html b/.sphinx/_templates/sidebar/search.html new file mode 100644 index 00000000..644a5ef6 --- /dev/null +++ b/.sphinx/_templates/sidebar/search.html @@ -0,0 +1,7 @@ + + diff --git a/.sphinx/requirements.txt b/.sphinx/requirements.txt new file mode 100644 index 00000000..e03a517b --- /dev/null +++ b/.sphinx/requirements.txt @@ -0,0 +1,19 @@ +# DO NOT MODIFY THIS FILE DIRECTLY! +# +# This file is generated automatically. +# Add custom requirements to the custom_required_modules +# array in the custom_conf.py file and run: +# make clean && make install +canonical-sphinx-extensions +furo +linkify-it-py +myst-parser +pyspelling +sphinx +sphinx-autobuild +sphinx-copybutton +sphinx-design +sphinx-reredirects +sphinx-tabs +sphinxcontrib-jquery +sphinxext-opengraph diff --git a/.sphinx/spellingcheck.yaml b/.sphinx/spellingcheck.yaml new file mode 100644 index 00000000..fc9d3c50 --- /dev/null +++ b/.sphinx/spellingcheck.yaml @@ -0,0 +1,29 @@ +matrix: +- name: rST files + aspell: + lang: en + d: en_GB + dictionary: + wordlists: + - .wordlist.txt + - .custom_wordlist.txt + output: .sphinx/.wordlist.dic + sources: + - _build/**/*.html + pipeline: + - pyspelling.filters.html: + comments: false + attributes: + - title + - alt + ignores: + - code + - pre + - spellexception + - link + - title + - div.relatedlinks + - strong.command + - div.visually-hidden + - img + - a.p-navigation__link diff --git a/.wokeignore b/.wokeignore deleted file mode 100644 index 8fa6b7a0..00000000 --- a/.wokeignore +++ /dev/null @@ -1,4 +0,0 @@ -* -!*/ -!*.md -!**/*.md diff --git a/.wordlist.txt b/.wordlist.txt index 1af9cd18..e3e8c9fa 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,338 +1,54 @@ -AAM -AAOS -AAPT -AAR -AArch -ABI -ABIs -ACLs -ADB -addon +# This wordlist is from the Sphinx starter pack and should not be +# modified. Add any custom terms to .custom_wordlist.txt instead. + addons -allocator -Altra -AMC -amd -AMI -AMS -analytics -Anbox -anonymization -ANR -anv -AOSP +API APIs -APK -APK's -APKs -AppArmor -Appium -ARMv -async -AttributeError -AudioTrack -backend balancer -balancers -bbr -benchmarking -binderfs -biometrics -bitrate -bitrates -Bluetooth -BombSquad -bool -boolean -BPF -bzip -cancellable -CDN -Center -CFS -cgroup -cgroup-v1 -cgroup-v2 -config -conformant Charmhub -Charmstore CLI -CloudFront -codec -codecs -Coturn -CPUs -crashdump -Crashpad -CSV -CTS -CUDA -customisable -customisation -customisations -CustomLocale -CVE -datacenter -dataset -deallocate -deallocated -DDoS -Debian -deprecations -Dev -DNS -dnsmasq -Dqlite -DrArm -drawio -DRM -easyrsa -Easy-RSA +Diátaxis +dropdown EBS -EFI -EFS -EGL -EINVAL -EmuGL -EOL -ERD -ETag -etcd -executables +EKS +enablement favicon -FEC -ffmpeg -FormatException -frontend -fullscreen -gamepad -gameplay -GL -Golang -GPG -GPUs +Furo +Git +GitHub Grafana -Graviton -Graylog -gRPC -gzip -HAProxy -HIDL -Honkai -hotfix -HTTPS -HW -HWE -HVAC IAM -idmapped -IDR -IME -impactful -Intra -IoT -IPC -IPs -iptables -init -interprocess -iOS -Javascript -Jira -jitter -JS +installable JSON Juju -Juju's -kb -keybinding -KeyError -keystore -KSM -Lawnchair -Libsoup -libwayland -Linux -linux -Livepatch -LLVMpipe -LMA -localhost +Kubeflow +Kubernetes +Launchpad +linter LTS -LXC -LXD -MAAS -macOS -middleware -Minetest -mutex -NACK -Nagios +Makefile +Matrix +Mattermost +MyST namespace -natively -NATs -netlink -NewPipe -NFS -NIC -NMEA -NRPE -nrpe -null -NUMA -numpad -NvEnc -NVIDIA -nvidia -NVMe -OAuth -OBB -OBD +namespaces +NodePort +Numbat observability -ODM -OES -OOB -OOM -OpenAPI -OpenGL -OpenStack -overcommitment -overcommitting -PCI -Perfetto -PKI -playout -Plex -PLI -powershell +OEM +OLM +Permalink pre -preselected -Quadro Quickstart -quickstart -radv -Rasterization -rasterization -RDNA -rc -README -rebased -Renderdoc -renderdoc -renderer -RenderThread -RESTful -RFE -RGBA -roadmap -RootFS -RSA -rsa -RTC -RTP -RTT -runtime -scalability -schedulable -scrcpy -SDK -SDKs -SEGV -SELinux -sendfile -SensorManager -SHA -shader -shiftfs -SIGBUS -signaling -simplestreams -SkiaPipeline -SLI -SMI -Snapcraft -snapd -spammy -SSD -SSL -SSO -SSRC -stderr -stdin -stdout -subcluster -subclusters -subcommand -subcommands -subnet -subnets -suboptimal -SurfaceFlinger -swiftshader -swrast -syscall -syscalls -systemd -SystemUI -telegraf -transcode -tryCapture -TCP -Telegraf -Tensorflow -timebase -TLS -Traefik -TypeError -UA -UDA -UDP +ReadMe +reST +reStructuredText +RTD +subdirectories +subfolders +subtree +Ubuntu UI -unencrypted -unexpose -unhandled -unpublish -unschedulable -untrusted -uptime -userspace -UTF -validator -vCPU -vCPUs -VHAL -VhalConnector -VhalPropertyStatus -viewport -VirGL -virglrenderer +UUID VM -VMs -VNC -VNDK -VPC -VPN -VPU -VPUs -vsync -Vulkan -vsync -Wayland -WebGL -WebRTC -WebSocket -websocket -websockets -WebView -WiFi -WGS -workspaces -WX -xz -YAML -ZFS -zpool -Uber -Unhold -upscaling +YAML \ No newline at end of file diff --git a/404.rst b/404.rst new file mode 100644 index 00000000..5dcc3d1d --- /dev/null +++ b/404.rst @@ -0,0 +1,26 @@ +:orphan: + +Page not found +============== + +.. grid:: 1 1 2 2 + :gutter: 5 + + .. grid-item:: + **Sorry, but the documentation page that you are looking for was + not found.** + + Documentation changes over time, and pages are moved around. + We try to redirect you to the updated content where possible, but + unfortunately, that didn't work this time (maybe because the content + you were looking for does not exist in this version of the + documentation). + + You can try to use the navigation to locate the content you're looking + for, or search for a similar page. + + .. grid-item:: + .. image:: 404.svg + :align: center + :scale: 65% + :alt: Penguin with a question mark \ No newline at end of file diff --git a/404.svg b/404.svg new file mode 100644 index 00000000..b353cd33 --- /dev/null +++ b/404.svg @@ -0,0 +1,13 @@ + + + + + + + + + diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..435e44bc --- /dev/null +++ b/Makefile @@ -0,0 +1,109 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXDIR = .sphinx +SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build +VENVDIR = $(SPHINXDIR)/venv +PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js +VENV = $(VENVDIR)/bin/activate + +.PHONY: help full-help woke-install pa11y-install install run html epub serve \ + clean clean-doc spelling linkcheck woke pa11y Makefile + +# Put it first so that "make" without argument is like "make help". +help: + @echo "\n" \ + "--------------------------------------------------------------- \n" \ + "* watch, build and serve the documentation: make run \n" \ + "* only build: make html \n" \ + "* only serve: make serve \n" \ + "* clean built doc files: make clean-doc \n" \ + "* clean full environment: make clean \n" \ + "* check links: make linkcheck \n" \ + "* check spelling: make spelling \n" \ + "* check inclusive language: make woke \n" \ + "* check accessibility: make pa11y \n" \ + "* other possible targets: make \n" \ + "--------------------------------------------------------------- \n" + +full-help: $(VENVDIR) + @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m" + @echo "Run 'make help' to see supported targets." + +# Shouldn't assume that venv is available on Ubuntu by default; discussion here: +# https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847 +$(SPHINXDIR)/requirements.txt: + python3 build_requirements.py + python3 -c "import venv" || sudo apt install python3-venv + +# If requirements are updated, venv should be rebuilt and timestamped. +$(VENVDIR): $(SPHINXDIR)/requirements.txt + @echo "... setting up virtualenv" + python3 -m venv $(VENVDIR) + . $(VENV); pip install --require-virtualenv \ + --upgrade -r $(SPHINXDIR)/requirements.txt \ + --log $(VENVDIR)/pip_install.log + @test ! -f $(VENVDIR)/pip_list.txt || \ + mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak + @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt + @touch $(VENVDIR) + +woke-install: + @type woke >/dev/null 2>&1 || \ + { echo "Installing \"woke\" snap... \n"; sudo snap install woke; } + +pa11y-install: + @type $(PA11Y) >/dev/null 2>&1 || { \ + echo "Installing \"pa11y\" from npm... \n"; \ + mkdir -p $(SPHINXDIR)/node_modules/ ; \ + npm install --prefix $(SPHINXDIR) pa11y; \ + } + +install: $(VENVDIR) + +run: install + . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + +# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. +html: install + . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +epub: install + . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +serve: html + cd "$(BUILDDIR)"; python3 -m http.server 8000 + +clean: clean-doc + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + rm -rf $(VENVDIR) + rm -f $(SPHINXDIR)/requirements.txt + rm -rf $(SPHINXDIR)/node_modules/ + +clean-doc: + git clean -fx "$(BUILDDIR)" + rm -rf $(SPHINXDIR)/.doctrees + +spelling: html + . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) + +linkcheck: install + . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + +woke: woke-install + woke *.rst **/*.rst --exit-1-on-failure \ + -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml + +pa11y: pa11y-install html + find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README.md b/README.md index a199a47b..4f550a78 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,65 @@ +--- +orphan: true +--- + # Anbox Cloud documentation -This repository hosts a copy of the documentation maintained on the [Ubuntu discourse](https://discourse.ubuntu.com) under the [Anbox Cloud > Documentation](https://discourse.ubuntu.com/c/anbox-cloud/documentation/50) category. This is predominantly the source for updating Anbox Cloud documentation and is published to Anbox Cloud documentation via discourse to enable community feedback and engagement. +This repository hosts the product documentation for Anbox Cloud. + +```{important} +The concepts of the Anbox component in Anbox Cloud are similar to the [Anbox open source project](https://github.com/anbox/anbox), but the Anbox open source project is an independent project that is not related to or used in Anbox Cloud. +``` + +## Contributing to Anbox Cloud documentation +You can contribute to the Anbox Cloud documentation through either of the following channels: +- Report an issue in GitHub +- Raise a pull request with your changes + +The Anbox Cloud team will review the issue/pull request and take the necessary action. + +### First-time contributors +We welcome your engagement with the Anbox Cloud community and appreciate all contributions, suggestions and feedback. There are many reasons why you should contribute to the Anbox Cloud documentation. + +- Improve your skills + + Contributing to the Anbox Cloud docs is a great way to improve your documentation and technical communication skills. You’ll get experience writing clear, concise documentation following [Diátaxis](https://diataxis.fr/) principles. + +- Learn more about Anbox Cloud + + Contributing to the Anbox Cloud documentation can help you broaden your understanding of the product and its related technologies. Writing documentation often involves exploring new features and investigating potential problems or challenges users may face, which can help you learn more about how Anbox Cloud works and how users interact with it. -## Pre-commit checks -* The following checks are run automatically before every commit: +- Connect with the Anbox Cloud user community + + As a user of Anbox Cloud, you’re encouraged to collaborate with other users and participate in discussions in the [Discourse forum](https://discourse.ubuntu.com/c/anbox-cloud/users/148). Contributing to the documentation is a great way to connect with other users and learn from their experiences. + +### Style and language + +Anbox Cloud documentation follows [Diátaxis](https://diataxis.fr/) principles. Before starting to contribute, we encourage you to familiarise yourself with Diátaxis. + +To accommodate different kinds of audience, try to: + +- Write content in a tone that’s appropriate for the subject. +- Write inclusively and assume very little prior knowledge of the reader. +- Link or explain phrases, acronyms and concepts that may be unfamiliar, and if unsure, err on the side of caution. + +We (mostly) adhere to the [Ubuntu style guide](https://docs.ubuntu.com/styleguide/en). Any deviations from the Ubuntu style guide are documented in the [Anbox Cloud documentation style guide](./contribute/anbox-style-guide.md). + +### Quality checks +* The following pre-commit checks are run automatically before every commit: - Inclusive language checks (`woke`) - Spellcheck (`spellcheck`) - - Link checker that verifies if discourse links are used for all internal links (`anbox-cloud-docs-links-checker`) -### Running pre-commit checks +#### Running pre-commit checks + +To be able to run these pre-commit checks: * Install the `pre-commit` package from the Ubuntu repositories. * Install the `aspell` and `aspell-en` packages from the Ubuntu repositories. This is required by the spellchecker. * Navigate to the top-level directory of this repository and run `pre-commit install --install-hooks`. -### Overriding pre-commit checks +#### Overriding pre-commit checks + +Enabling pre-commit checks are optional as these checks are executed on pull requests automatically. If you do not want to run these checks before commits or to skip a particular check, use the following tips: * To disable the pre-commit hook, use `--no-verify` when running `git commit`. * To skip a particular pre-commit check, prefix `SKIP=` when running `git commit`. diff --git a/build_requirements.py b/build_requirements.py new file mode 100644 index 00000000..e1ccb4ac --- /dev/null +++ b/build_requirements.py @@ -0,0 +1,118 @@ +import sys + +sys.path.append('./') +from custom_conf import * + +# The file contains helper functions and the mechanism to build the +# .sphinx/requirements.txt file that is needed to set up the virtual +# environment. + +# You should not do any modifications to this file. Put your custom +# requirements into the custom_required_modules array in the custom_conf.py +# file. If you need to change this file, contribute the changes upstream. + +legacyCanonicalSphinxExtensionNames = [ + "youtube-links", + "related-links", + "custom-rst-roles", + "terminal-output" + ] + +def IsAnyCanonicalSphinxExtensionUsed(): + for extension in custom_extensions: + if (extension.startswith("canonical.") or + extension in legacyCanonicalSphinxExtensionNames): + return True + + return False + +def IsSphinxTabsUsed(): + for extension in custom_extensions: + if extension.startswith("sphinx_tabs."): + return True + + return False + +def AreRedirectsDefined(): + return ("sphinx_reredirects" in custom_extensions) or ( + ("redirects" in globals()) and \ + (redirects is not None) and \ + (len(redirects) > 0)) + +def IsOpenGraphConfigured(): + if "sphinxext.opengraph" in custom_extensions: + return True + + for global_variable_name in list(globals()): + if global_variable_name.startswith("ogp_"): + return True + + return False + +def IsMyStParserUsed(): + return ("myst_parser" in custom_extensions) or \ + ("custom_myst_extensions" in globals()) + +def DeduplicateExtensions(extensionNames: [str]): + extensionNames = dict.fromkeys(extensionNames) + resultList = [] + encounteredCanonicalExtensions = [] + + for extensionName in extensionNames: + if extensionName in legacyCanonicalSphinxExtensionNames: + extensionName = "canonical." + extensionName + + if extensionName.startswith("canonical."): + if extensionName not in encounteredCanonicalExtensions: + encounteredCanonicalExtensions.append(extensionName) + resultList.append(extensionName) + else: + resultList.append(extensionName) + + return resultList + +if __name__ == "__main__": + requirements = [ + "furo", + "pyspelling", + "sphinx", + "sphinx-autobuild", + "sphinx-copybutton", + "sphinx-design", + "sphinxcontrib-jquery" + ] + + requirements.extend(custom_required_modules) + + if IsAnyCanonicalSphinxExtensionUsed(): + requirements.append("canonical-sphinx-extensions") + + if IsSphinxTabsUsed(): + requirements.append("sphinx-tabs") + + if AreRedirectsDefined(): + requirements.append("sphinx-reredirects") + + if IsOpenGraphConfigured(): + requirements.append("sphinxext-opengraph") + + if IsMyStParserUsed(): + requirements.append("myst-parser") + requirements.append("linkify-it-py") + + # removes duplicate entries + requirements = list(dict.fromkeys(requirements)) + requirements.sort() + + with open(".sphinx/requirements.txt", 'w') as requirements_file: + requirements_file.write( + "# DO NOT MODIFY THIS FILE DIRECTLY!\n" + "#\n" + "# This file is generated automatically.\n" + "# Add custom requirements to the custom_required_modules\n" + "# array in the custom_conf.py file and run:\n" + "# make clean && make install\n") + + for requirement in requirements: + requirements_file.write(requirement) + requirements_file.write('\n') diff --git a/check-spelling.sh b/check-spelling.sh deleted file mode 100755 index d4432d7b..00000000 --- a/check-spelling.sh +++ /dev/null @@ -1,2 +0,0 @@ -#!/bin/sh -python3 -m pyspelling -c .spellcheck.yaml diff --git a/conf.py b/conf.py new file mode 100644 index 00000000..dfbd56d0 --- /dev/null +++ b/conf.py @@ -0,0 +1,135 @@ +import sys + +sys.path.append('./') +from custom_conf import * +from build_requirements import * + +# Configuration file for the Sphinx documentation builder. +# You should not do any modifications to this file. Put your custom +# configuration into the custom_conf.py file. +# If you need to change this file, contribute the changes upstream. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +############################################################ +### Extensions +############################################################ + +extensions = [ + 'sphinx_design', + 'sphinx_copybutton', + 'sphinxcontrib.jquery', +] + +# Only add redirects extension if any redirects are specified. +if AreRedirectsDefined(): + extensions.append('sphinx_reredirects') + +# Only add myst extensions if any configuration is present. +if IsMyStParserUsed(): + extensions.append('myst_parser') + + # Additional MyST syntax + myst_enable_extensions = [ + 'substitution', + 'deflist', + 'linkify' + ] + myst_enable_extensions.extend(custom_myst_extensions) + +# Only add Open Graph extension if any configuration is present. +if IsOpenGraphConfigured(): + extensions.append('sphinxext.opengraph') + +extensions.extend(custom_extensions) +extensions = DeduplicateExtensions(extensions) + +### Configuration for extensions + +# Used for related links +if not 'discourse_prefix' in html_context and 'discourse' in html_context: + html_context['discourse_prefix'] = html_context['discourse'] + '/t/' + +# Default image for OGP (to prevent font errors, see +# https://github.com/canonical/sphinx-docs-starter-pack/pull/54 ) +if not 'ogp_image' in locals(): + ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg' + +############################################################ +### General configuration +############################################################ + +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + '.sphinx', +] +exclude_patterns.extend(custom_excludes) + +rst_epilog = ''' +.. include:: /reuse/links.txt +''' +if 'custom_rst_epilog' in locals(): + rst_epilog = custom_rst_epilog + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +if not 'conf_py_path' in html_context and 'github_folder' in html_context: + html_context['conf_py_path'] = html_context['github_folder'] + +# For ignoring specific links +linkcheck_anchors_ignore_for_url = [ + r'https://github\.com/.*' +] +linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url) + +# Tags cannot be added directly in custom_conf.py, so add them here +for tag in custom_tags: + tags.add(tag) + +############################################################ +### Styling +############################################################ + +# Find the current builder +builder = 'dirhtml' +if '-b' in sys.argv: + builder = sys.argv[sys.argv.index('-b')+1] + +# Setting templates_path for epub makes the build fail +if builder == 'dirhtml' or builder == 'html': + templates_path = ['.sphinx/_templates'] + +# Theme configuration +html_theme = 'furo' +html_last_updated_fmt = '' +html_permalinks_icon = '¶' + +if html_title == '': + html_theme_options = { + 'sidebar_hide_name': True + } + +############################################################ +### Additional files +############################################################ + +html_static_path = ['.sphinx/_static'] + +html_css_files = [ + 'custom.css', + 'header.css', + 'github_issue_links.css', + 'furo_colors.css' +] +html_css_files.extend(custom_html_css_files) + +html_js_files = ['header-nav.js'] +if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button: + html_js_files.append('github_issue_links.js') +html_js_files.extend(custom_html_js_files) diff --git a/contribute/anbox-style-guide.md b/contribute/anbox-style-guide.md new file mode 100644 index 00000000..ae3edf74 --- /dev/null +++ b/contribute/anbox-style-guide.md @@ -0,0 +1,82 @@ + +(style-guide)= +# Anbox Cloud Documentation Style Guide + +Anbox Cloud documentation’s navigational structure, style, and content follows the Diátaxis systematic framework for technical documentation authoring. So the information is categorised into tutorials, how-to guides, reference material, and explanatory text. See [Diátaxis](https://diataxis.fr/). + +This product-specific style guide lists any extra guidelines or deviations from the [Ubuntu style guide](https://docs.ubuntu.com/styleguide/en). + +## Format + +Anbox Cloud documentation is written in a combination of MyST and Markdown syntax. + +## General + +* Use inclusive language and assume a friendly tone rather than an overly formal one. +* Use monospaced font for: + * Inline code and code blocks + * File names + * References to utilities/programs + * File and directory paths + * Command options +* Avoid long sentences. If it is a complex statement, try and break it down into multiple sentences. While the Canonical copy style guide has guidance about hyphens when joining words, it does not elaborate much on prefixes. +* Use bold and italics very sparingly. Use italics for user interface fields and bold for UI elements that call for action. +* Use single spaces between sentences. +* Use angle brackets to indicate variables. +* All extra white space should be removed, especially at the end of lines. +* Add a new line at the end of the file. + +## Section titles + +* Insert a blank line after a section title. +* Do not skip heading levels when creating sections. +* Avoid using multiple section titles sequentially without any text between them. +* Avoid manual HTML anchors, links to section titles can be picked up from the page-level table of contents. + +## Admonishments + +While admonishments can be useful to convey important information, they can be a distraction when used often. So before adding an admonishment, assess if the content really belongs in one. + +Keeping the types of admonishments to a minimum could be simplistic and also reduce cognitive overload on the reader. Stick to the following types of admonishments: + +* Note +* Important +* Tip +* Caution + +## Language + +### Oxford/Serial Comma + +The Anbox Cloud documentation does not use the oxford comma but exceptions are allowed for the sake of technical accuracy and ease of readability. + +### Hyphens for Prefixes + +Use hyphens when the starting letter of a word is in capital case or starts with a vowel. In other cases, do not hyphenate and use it as a single word. + + **Note:** You might be required to add such words to the wordlist as spellcheck could flag these words. + +**Examples:** +* `Pre-employment` +* `Preconfigure` + +## Terminology + +* It’s always “Anbox Cloud Appliance” when used in full form and “appliance” when used generically. +* Always use product name in full form with capitalisation - "Anbox Cloud". +* Within the context of Anbox Cloud, such as AMS, you can use the term "Anbox images" or "Anbox instances". When documenting about LXD images or containers that contain Anbox specific configuration from a big picture point of view,such as the architecture, use the term as "LXD images" or "LXD containers". When there is scope for ambiguity, elaborate and use as "LXD images with Anbox Cloud configuration". + +## Images and screenshots + +While images and screenshots are very helpful in visual appeal and getting the message across to the readers, they can be hard to maintain and cause overhead if they change too often. So use images or screenshots only when they: + +* Do not change often requiring updates for every release. +* Explain the concept better than text or it should strongly reinforce the concept explained in the text. +* Add to the reader’s understanding rather than just providing a step by step visual of the user interface. +* Break the monotony of continuous text information when trying to accomplish a tough procedure. + +Simple images can be made using an image editor of your choice or you can use [diagrams.net](https://www.diagrams.net). + +## Redirects + +Add redirects whenever a file path changes as it affects the URL of the page. diff --git a/contribute/landing.md b/contribute/landing.md new file mode 100644 index 00000000..d2c125e4 --- /dev/null +++ b/contribute/landing.md @@ -0,0 +1,19 @@ +(contribute)= +# Contribute to Anbox Cloud documentation + +Although Anbox Cloud is a closed-source product, the documentation for Anbox Cloud is open and is available in the [`anbox-cloud-docs` repository on GitHub](https://github.com/canonical/anbox-cloud-docs). + +We welcome contributions, suggestions, fixes and constructive feedback from the user community. If you feel something is inaccurate, unclear or broken, you have a number of ways to fix it: + +- Fix the issue and [raise a pull request](https://github.com/canonical/anbox-cloud-docs/pulls) against the docs repository. +- Report it as a bug on [Launchpad](https://bugs.launchpad.net/anbox-cloud/+bugs) or on [GitHub](https://github.com/canonical/anbox-cloud-docs/issues/new). +- Talk to us on the [public Matrix channel](https://matrix.to/#/#anbox-cloud:ubuntu.com). + +The navigational structure, style, and content of our documentation follows the Diátaxis systematic framework for technical documentation. This categorises the documentation into tutorials, how-to guides, reference material and explanatory text. + +Consistency is vital in documentation, which is why we request contributors to follow the {ref}`style-guide`. However, do not let this be a barrier to your contribution. You can still submit contributions to the best of your ability, and if something is inconsistent, we will fix it. We are targeting continuous improvement rather than delayed perfection. + +```{toctree} +:hidden: +anbox-style-guide +``` \ No newline at end of file diff --git a/custom_conf.py b/custom_conf.py new file mode 100644 index 00000000..96f2479e --- /dev/null +++ b/custom_conf.py @@ -0,0 +1,214 @@ +import datetime + +# Custom configuration for the Sphinx documentation builder. +# All configuration specific to your project should be done in this file. +# +# The file is included in the common conf.py configuration file. +# You can modify any of the settings below or add any configuration that +# is not covered by the common conf.py file. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# +# If you're not familiar with Sphinx and don't want to use advanced +# features, it is sufficient to update the settings in the "Project +# information" section. + +############################################################ +### Project information +############################################################ + +# Product name +project = 'Canonical Anbox Cloud' +author = 'Anbox Cloud team' + +# The title you want to display for the documentation in the sidebar. +# You might want to include a version number here. +# To not display any title, set this option to an empty string. +html_title = 'Anbox Cloud documentation' + +# The default value uses the current year as the copyright year. +# +# For static works, it is common to provide the year of first publication. +# Another option is to give the first year and the current year +# for documentation that is often changed, e.g. 2022–2023 (note the en-dash). +# +# A way to check a GitHub repo's creation date is to obtain a classic GitHub +# token with 'repo' permissions here: https://github.com/settings/tokens +# Next, use 'curl' and 'jq' to extract the date from the GitHub API's output: +# +# curl -H 'Authorization: token ' \ +# -H 'Accept: application/vnd.github.v3.raw' \ +# https://api.github.com/repos/canonical/ | jq '.created_at' + +copyright = '%s, %s' % (datetime.date.today().year, author) + +## Open Graph configuration - defines what is displayed as a link preview +## when linking to the documentation from another website (see https://ogp.me/) +# The URL where the documentation will be hosted (leave empty if you +# don't know yet) +# NOTE: If no ogp_* variable is defined (e.g. if you remove this section) the +# sphinxext.opengraph extension will be disabled. +ogp_site_url = 'https://canonical-anbox-cloud.readthedocs-hosted.com/' +# The documentation website name (usually the same as the product name) +ogp_site_name = 'Anbox Cloud documentation' +# The URL of an image or logo that is used in the preview +ogp_image = 'https://assets.ubuntu.com/v1/04242fd4-Anbox-logo-2022_square.svg' + +# Update with the local path to the favicon for your product +# (default is the circle of friends) +html_favicon = '.sphinx/_static/favicon.png' + +# (Some settings must be part of the html_context dictionary, while others +# are on root level. Don't move the settings.) +html_context = { + + # Change to the link to the website of your product (without "https://") + # For example: "ubuntu.com/lxd" or "microcloud.is" + # If there is no product website, edit the header template to remove the + # link (see the readme for instructions). + 'product_page': 'anbox-cloud.io', + + # Add your product tag (the orange part of your logo, will be used in the + # header) to ".sphinx/_static" and change the path here (start with "_static") + # (default is the circle of friends) + 'product_tag': '_static/logo.svg', + + # Change to the discourse instance you want to be able to link to + # using the :discourse: metadata at the top of a file + # (use an empty value if you don't want to link) + 'discourse': 'https://discourse.ubuntu.com', + 'discourse_users': 'https://discourse.ubuntu.com/c/anbox-cloud/users/148', + + # Change to the Mattermost channel you want to link to + # (use an empty value if you don't want to link) + 'mattermost': '', + + # Change to the GitHub URL for your project + 'github_url': 'https://github.com/canonical/anbox-cloud-docs', + + # Change to the branch for this version of the documentation + 'github_version': 'main', + + # Change to the folder that contains the documentation + # (usually "/" or "/docs/") + 'github_folder': '/', + + # Change to an empty value if your GitHub repo doesn't have issues enabled. + # This will disable the feedback button and the issue link in the footer. + 'github_issues': 'enabled', + + # Controls the existence of Previous / Next buttons at the bottom of pages + # Valid options: none, prev, next, both + 'sequential_nav': 'both', +} + +# If your project is on documentation.ubuntu.com, specify the project +# slug (for example, "lxd") here. +slug = "docs" + +############################################################ +### Redirects +############################################################ + +# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html) +# For example: 'explanation/old-name.html': '../how-to/prettify.html', +# You can also configure redirects in the Read the Docs project dashboard +# (see https://docs.readthedocs.io/en/stable/guides/redirects.html). +# NOTE: If this variable is not defined, set to None, or the dictionary is empty, +# the sphinx_reredirects extension will be disabled. +redirects = { + 'howto/container': 'howto/instance', +} + +############################################################ +### Link checker exceptions +############################################################ + +# Links to ignore when checking links +linkcheck_ignore = [ + 'http://127.0.0.1:8000', + 'https://support.canonical.com/', + 'https://assets.ubuntu.com/manager' + ] + +# This setting will check the links but not the anchors +# This list will be appended to linkcheck_anchors_ignore_for_url +custom_linkcheck_anchors_ignore_for_url = [ + r'https://matrix\.to/.*', + r'https://canonical\.github\.io/anbox-cloud\.github\.com/.*', + r'https://juju.is/docs/juju/.*', +] + +# Pages to ignore for link check +linkcheck_exclude_documents = [ + r'.*/release-notes/.*' +] + +############################################################ +### Additions to default configuration +############################################################ + +## The following settings are appended to the default configuration. +## Use them to extend the default functionality. +# NOTE: Remove this variable to disable the MyST parser extensions. +custom_myst_extensions = [] + +# Add custom Sphinx extensions as needed. +# This array contains recommended extensions that should be used. +# NOTE: The following extensions are handled automatically and do +# not need to be added here: myst_parser, sphinx_copybutton, sphinx_design, +# sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph +custom_extensions = [ + 'sphinx_tabs.tabs', + 'canonical.youtube-links', + 'canonical.related-links', + 'canonical.custom-rst-roles', + 'canonical.terminal-output' + ] + +# Add custom required Python modules that must be added to the +# .sphin x/requirements.txt file. +# NOTE: The following modules are handled automatically and do not need to be +# added here: canonical-sphinx-extensions, furo, linkify-it-py, myst-parser, +# pyspelling, sphinx, sphinx-autobuild, sphinx-copybutton, sphinx-design, +# sphinx-reredirects, sphinx-tabs, sphinxcontrib-jquery, sphinxext-opengraph +custom_required_modules = [] + +# Add files or directories that should be excluded from processing. +custom_excludes = [ + 'doc-cheat-sheet*', + ] + +# Add CSS files (located in .sphinx/_static/) +custom_html_css_files = [] + +# Add JavaScript files (located in .sphinx/_static/) +custom_html_js_files = [] + +## The following settings override the default configuration. + +# Specify a reST string that is included at the end of each file. +# If commented out, use the default (which pulls the reuse/links.txt +# file into each reST file). +# custom_rst_epilog = '' + +# By default, the documentation includes a feedback button at the top. +# You can disable it by setting the following configuration to True. +disable_feedback_button = False + +# Add tags that you want to use for conditional inclusion of text +# (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags) +custom_tags = [] + +############################################################ +### Additional configuration +############################################################ + +## Add any configuration that is not covered by the common conf.py file. + +# Define a :center: role that can be used to center the content of table cells. +rst_prolog = ''' +.. role:: center + :class: align-center +''' diff --git a/explanation/aaos.md b/explanation/aaos.md index d25ccb02..70bcda30 100644 --- a/explanation/aaos.md +++ b/explanation/aaos.md @@ -1,12 +1,14 @@ +# Android Automotive OS(AAOS) + Since the 1.21.0 release, in addition to providing images based on the Android Open Source Project (AOSP), Anbox Cloud also offers images based on the [Android Automotive OS (AAOS)](https://source.android.com/docs/automotive/start/what_automotive). These images help run Android in automotive infotainment systems at scale. -[note type="information" status="Important"] +```{important} * This is currently an experimental feature. * The Anbox Cloud AAOS images are based on Android Automotive and *not* Android Auto. For understanding the differences between the two, see upstream documentation on [Android Automotive and Android Auto](https://source.android.com/docs/automotive/start/what_automotive#android-automotive-android-auto). -[/note] +``` The [Vehicle Abstraction Layer (VHAL)](https://source.android.com/docs/automotive/vhal) enables Android Automotive to communicate with and control the different vehicle hardware controls. -## Related information +## Related topics -* [Supported features (AOSP vs AAOS)](https://discourse.ubuntu.com/t/supported-features-aosp-vs-aaos/42520) +* {ref}`ref-aosp-aaos` diff --git a/explanation/aar.md b/explanation/aar.md index 5d6d45ff..3aa4b6bf 100644 --- a/explanation/aar.md +++ b/explanation/aar.md @@ -1,3 +1,6 @@ +(exp-aar)= +# Anbox Application Registry + The Anbox Application Registry (AAR) provides a central repository for applications created on Anbox Cloud. Using an AAR is very useful for larger deployments involving multiple regions, in order to keep applications in sync. ## How AAR works @@ -18,8 +21,8 @@ AMS can act in two different roles, `publisher` or `client` when working with an The `client` role allows only read access to the AAR. AMS instances registered as clients consume the applications pushed by the publishers. -## Related information +## Related topics -* [How to deploy an AAR](https://discourse.ubuntu.com/t/installation-application-registry/17749) -* [How to configure an AAR](https://discourse.ubuntu.com/t/configure-an-aar/24319) -* [How to revoke an AAR client](https://discourse.ubuntu.com/t/revoke-an-aar-client/24320) +* {ref}`howto-deploy-aar` +* {ref}`howto-configure-aar` +* {ref}`howto-revoke-aar` diff --git a/explanation/addons.md b/explanation/addons.md index 008d0005..132e5414 100644 --- a/explanation/addons.md +++ b/explanation/addons.md @@ -1,4 +1,7 @@ -Addons provide a way to extend and customise images in Anbox Cloud. Once you have created addons, you can create [hooks](https://discourse.ubuntu.com/t/28555) for them that are triggered based on events in the life cycle of an [instance](https://discourse.ubuntu.com/t/26204#instance). You can create addons independently and later attach it to individual applications. +(exp-addons)= +# Addons + +Addons provide a way to extend and customise images in Anbox Cloud. Once you have created addons, you can create hooks for them that are triggered based on events in the life cycle of an instance. You can create addons independently and later attach it to individual applications. ## Best practices while using addons @@ -10,20 +13,26 @@ Here are some good practices to consider when creating addons: Addons are executed synchronously. Any addon that performs long-running operations (for example, downloading large files, installing packages on regular instances or querying unresponsive services) will delay an application from starting. -[note type="information" Status="Tip"]Use the `INSTANCE_TYPE` environment variable to run only on the specified instance type. Doing so runs the code in your hooks only when necessary.[/note] +```{tip} +Use the `INSTANCE_TYPE` environment variable to run only on the specified instance type. Doing so runs the code in your hooks only when necessary. +``` ### Use global addons sparingly Addons that are enabled for all applications can be useful, but they can add up quickly because whenever a global addon gets updated, a new application version is created. So if you use a global addon and that addon gets updated often, the disk capacity fills up fast. -Try to attach addons to individual applications unless you need a [global addon](https://discourse.ubuntu.com/t/how-to-enable-an-addon-globally/25285). +Try to attach addons to individual applications unless you need a global addon. See {ref}`howto-enable-addons-globally` for more information. ### Clean up your addons -For base instances, if your addon needs additional tools and dependencies during its installation, make sure you remove them afterwards (as part of the [`post-stop` hook](https://discourse.ubuntu.com/t/hooks/28555)). This will make your application image lighter and all instances launched from it will start faster. +For base instances, if your addon needs additional tools and dependencies during its installation, make sure you remove them afterwards (as part of the `post-stop` hook). This will make your application image lighter and all instances launched from it will start faster. + + +## Related topics +* {ref}`exp-instances` +* {ref}`tut-create-addon` +* {ref}`howto-addons` +* {ref}`ref-hooks` -## Related information -* [Tutorial: Create an addon](https://discourse.ubuntu.com/t/creating-an-addon/25284) -* [How to use addons](https://discourse.ubuntu.com/t/managing-addons/17759) diff --git a/explanation/ams.md b/explanation/ams.md index 0111502a..0de0cacc 100644 --- a/explanation/ams.md +++ b/explanation/ams.md @@ -1,3 +1,6 @@ +(exp-ams)= +# Anbox Management Service + The Anbox Management Service (AMS) sits at the heart of Anbox Cloud and handles all aspects of the application and instance life cycle. It is responsible for managing instances, applications, addons, updates and more, while simultaneously ensuring high density, performance and fast startup times. ## Interacting with AMS @@ -6,8 +9,9 @@ AMS is usually managed through the command line interface, the Anbox Management Since AMS exposes an HTTP interface, any tool can use the [AMS HTTP API](https://canonical.github.io/anbox-cloud.github.com/latest/ams/) to interact with AMS. Both the AMC (when running as a remote client) and the Anbox Application Registry (AAR) use the AMS HTTP API to interact with AMS. -You can also develop your own client by using the [AMS SDK](https://discourse.ubuntu.com/t/ams-sdk-api-reference/17845). +You can also develop your own client by using the {ref}`sec-ams-sdk`. +(sec-security-cert-remote-clients)= ### Security certificates for remote clients If the AMC is running on the same machine as AMS, it communicates with AMS through a UNIX domain socket, not through HTTP. Therefore, you do not need to worry about security certificates for local clients. However, in case of remote clients, interacting with AMS through HTTP requires a secure and trusted setup for communications, using TLS and [certificates](https://en.wikipedia.org/wiki/X.509). @@ -44,10 +48,12 @@ As an alternative to using AMC, you can develop a custom client built around you You can access AMS either by IP or through a UNIX socket. The IP depends on your network, but the UNIX socket will always be located at `/var/snap/ams/common/server/unix.socket` on the machine that hosts AMS. -[note type="information" status="Tip"]If your client requires the AMS certificate, you can find it in `/var/snap/ams/common/server/ams.crt`.[/note] +```{tip} +If your client requires the AMS certificate, you can find it in `/var/snap/ams/common/server/ams.crt`. +``` -## Related information +## Related topics -* [How to control AMS remotely](https://discourse.ubuntu.com/t/managing-ams-access/17774) -* [AMS configuration](https://discourse.ubuntu.com/t/ams-configuration/20872) -* [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/application-registry/17761) +* {ref}`exp-aar` +* {ref}`howto-access-ams-remote` +* {ref}`ref-ams-configuration` \ No newline at end of file diff --git a/explanation/anbox-cloud.md b/explanation/anbox-cloud.md index f7a7ee41..36af4fee 100644 --- a/explanation/anbox-cloud.md +++ b/explanation/anbox-cloud.md @@ -1,9 +1,13 @@ +(exp-anbox-cloud)= +# Anbox Cloud + Anbox Cloud provides a rich software stack that enables you to run Android applications in the cloud for different use cases, including high-performance streaming of graphics to desktop and mobile client devices. -Anbox Cloud maintains a single Android system per [instance](https://discourse.ubuntu.com/t/26204#instance), providing higher density and better performance per host while ensuring security and isolation of each instance. Depending on the target platform, payload, and desired application performance (for example, frame rate), Anbox Cloud can run more than 100 instances on a single machine. +Anbox Cloud maintains a single Android system per instance, providing higher density and better performance per host while ensuring security and isolation of each instance. Depending on the target platform, payload, and desired application performance (for example, frame rate), Anbox Cloud can run more than 100 instances on a single machine. Watch [this video](https://youtu.be/P7md88WhOC0?si=eUGiQtQ-9uXmZOQu) to learn more about how you can deploy Anbox Cloud with charms. +(sec-variants)= ## Variants Anbox Cloud comes in two variants that serve different purposes: @@ -20,14 +24,14 @@ See the following table for a comparison of features for the different variants: | Feature | Anbox Cloud Appliance | Anbox Cloud | |---------|-----------------------|-------------| -| [Streaming capabilities](https://discourse.ubuntu.com/t/streaming-android-applications/17769) | ✓ | ✓ | -| [Web dashboard](https://discourse.ubuntu.com/t/web-dashboard/20871) | ✓ | ✓ | -| [Android version](https://discourse.ubuntu.com/t/provided-images/24185) | 12, 13 | 12, 13 | +| {ref}`exp-application-streaming` | ✓ | ✓ | +| {ref}`exp-web-dashboard` | ✓ | ✓ | +| {ref}`Android versions ` | 12, 13 | 12, 13 | | [Security updates](https://ubuntu.com/support) | ✓ | ✓ | -| [Community support](https://discourse.ubuntu.com/c/anbox-cloud/) | ✓ | ✓ | +| [Community support](https://discourse.ubuntu.com/c/anbox-cloud/users/148) | ✓ | ✓ | | [Vendor support available](https://ubuntu.com/support) | ✓* | ✓ | -| [Clustering support](https://discourse.ubuntu.com/t/clustering/17765)| - | ✓ | -| [Custom images](https://discourse.ubuntu.com/t/custom-images/45071)| ✓ | ✓ | +| {ref}`exp-clustering`| - | ✓ | +| {ref}`exp-custom-images`| ✓ | ✓ | *\* When purchasing the Anbox Cloud Appliance through the AWS Marketplace, the Ubuntu Pro subscription does not include vendor support.* @@ -55,7 +59,7 @@ Inside each Anbox subcluster, the following components are present: Users can connect to AMS via CLI or HTTP API calls on port 8444. AMS is installed as a snap on each of the control nodes and interacts with the instances, requesting and releasing resources as per demand. -* **Anbox Management Client (AMC)** - You can choose to install AMC on other machines to [control AMS remotely](https://discourse.ubuntu.com/t/how-to-control-ams-remotely/17774), but it is generally installed together with AMS. A developer or system administrator will manage AMS through the command line interface (AMC) or through custom-built tools interacting with the AMS HTTP API. +* **Anbox Management Client (AMC)** - You can choose to install AMC on other machines to {ref}`control AMS remotely `, but it is generally installed together with AMS. A developer or system administrator will manage AMS through the command line interface (AMC) or through custom-built tools interacting with the AMS HTTP API. * **etcd** - etcd is the database that is used to store the data managed by AMS. It provides a reliable way to store data across a cluster of machines. It gracefully handles primary node selections when a network is split into subnets and will tolerate machine failure. For more information, see [etcd](https://etcd.io/). @@ -65,7 +69,9 @@ Each Anbox subcluster also has a number of LXD worker nodes that form a LXD clus * **LXD** - The LXD daemon spawns a number of LXD instances containing Anbox-related configuration. These instances provide an Ubuntu environment that uses the hardware of the LXD worker node, including CPUs, disks, networks, and if available, GPUs. Each LXD instance runs exactly one Android instance that the end user can access/stream. - [note type="information" status="Note"] The term LXD instance means that they are LXD containers or virtual machines that contain configuration related to Anbox Cloud. Within the context of Anbox Cloud, the term Anbox Cloud images is used interchangeably with LXD images in the sense that they are LXD images containing specific configuration related to Anbox Cloud.[/note] + ```{note} + The term LXD instance means that they are LXD containers or virtual machines that contain configuration related to Anbox Cloud. Within the context of Anbox Cloud, the term Anbox Cloud images is used interchangeably with LXD images in the sense that they are LXD images containing specific configuration related to Anbox Cloud. + ``` * **AMS node controller** – The AMS node controller puts the appropriate firewall rules in place when an instance is started or stopped to control ingress and egress traffic. @@ -93,7 +99,7 @@ You also need an additional machine to host the streaming stack control plane wi You will be required to provide one or more frontend services. A frontend service authenticates the client with the stream gateway and can provide other functionality, such as, selecting a game. -For example, your web client can be a mobile app used to access the provided Android containers. We provide the [Anbox Streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844) as a starting point for creating a web client. The web dashboard in Anbox Cloud is an example for a frontend service and web client, combined into one. +For example, your web client can be a mobile app used to access the provided Android containers. We provide the {ref}`sec-streaming-sdk` as a starting point for creating a web client. The web dashboard in Anbox Cloud is an example for a frontend service and web client, combined into one. ## LXD @@ -119,17 +125,18 @@ If you want to monitor LXD, you can always run `lxc list` to display the existin | juju-34631c-0 | RUNNING | 240.0.180.30 (eth0) | | CONTAINER | 0 | lxd0 | +--------------------------+---------+------------------------+------+-----------+-----------+----------+ ``` - +(sec-lxd-storage)= ### LXD storage For LXD storage, Anbox Cloud uses a ZFS storage pool, which it creates automatically. This storage pool can be located on either a dedicated block storage device or a loop file. See [Data storage location](https://documentation.ubuntu.com/lxd/en/latest/explanation/storage/#data-storage-location) in the LXD documentation for more information. While a loop file is easy to set up, it is much slower than a block device. Therefore, we recommend using a block device that is dedicated to LXD storage only. -If you are doing a full deployment, configure the storage before starting the deployment. See the *Customise storage* section in [How to deploy Anbox Cloud with Juju](https://discourse.ubuntu.com/t/install-with-juju/17744#customise-storage) or [How to deploy Anbox Cloud on bare metal](https://discourse.ubuntu.com/t/deploy-anbox-cloud-on-bare-metal/26378#customise-storage) for instructions. If you skip the configuration, Anbox Cloud sets up a loop-file with an automatically calculated size, which is not recommended. +If you are doing a full deployment, configure the storage before starting the deployment. See {ref}`customise storage when deploying with Juju ` or {ref}`customise storage when deploying on bare metal ` for instructions. If you skip the configuration, Anbox Cloud sets up a loop-file with an automatically calculated size, which is not recommended. If you are using the Anbox Cloud Appliance, you are prompted during the initialisation process to specify the storage location, and, if you choose a loop file, its size. When choosing a size, keep in mind that the loop file cannot be larger than the root disk, and that it will cause the disk to fill up as the loop file grows to its maximum size over time. The created storage pool is used to store all Anbox Cloud content, including the instances created by Juju. +(sec-juju-bundles)= ## Juju bundles The regular Anbox Cloud variant provides two different Juju bundles: @@ -142,10 +149,14 @@ The regular Anbox Cloud variant provides two different Juju bundles: For more information, see the [charm page](https://charmhub.io/anbox-cloud). -[note type="information" status="Tip"] +```{tip} For detailed information about the charm, check the `bundle.yaml` file in the bundle. You can download the bundle with `juju download `, thus `juju download anbox-cloud-core` or `juju download anbox-cloud`. Unzip the bundle to access the `bundle.yaml` file. -[/note] +``` + +If you don't need to stream the visual output of the Android containers, you can use the `anbox-cloud-core` bundle. Otherwise, you should use the `anbox-cloud` bundle. However, even without the streaming stack, there are still ways to get visual access for inspection purposes. See {ref}`howto-access-instance` for more information. + +## Related topics -If you don't need to stream the visual output of the Android containers, you can use the `anbox-cloud-core` bundle. Otherwise, you should use the `anbox-cloud` bundle. However, even without the streaming stack, there are still ways to get visual access for inspection purposes. See [How to access an instance](https://discourse.ubuntu.com/t/17772) for details. +* {ref}`exp-instances` \ No newline at end of file diff --git a/explanation/application-streaming.md b/explanation/application-streaming.md index 80d37c45..25e820a0 100644 --- a/explanation/application-streaming.md +++ b/explanation/application-streaming.md @@ -1,4 +1,7 @@ -This guide covers the usage of the Streaming Stack and assumes that you know [how to get access to the Stream Gateway API](https://discourse.ubuntu.com/t/access-the-stream-gateway/17784). +(exp-application-streaming)= +# Application streaming + +This guide covers the usage of the streaming stack and assumes that you know how to access the stream gateway. If you are not familiar with accessing the stream gateway, see {ref}`howto-access-stream-gateway`. ## Streaming stack overview @@ -67,12 +70,12 @@ Starting from 1.22.0, Anbox Cloud offers a much simpler way to create instances You can request AMS to create an instance and AMS will be able to dynamically create a session for the newly launched instance by contacting the stream agent. The agent mediates communication between stream gateway and AMS and provides the necessary session information to the AMS. The AMS proceeds with successfully creating an instance that can be streamed. -[note type="information" status="Note"] +```{note} If you do not enable streaming when launching the instance, you cannot enable it on that instance later. You will have to launch a new instance with streaming enabled. -[/note] +``` -## Related information +## Related topics -* [Installing Streaming Stack](https://discourse.ubuntu.com/t/installation-quickstart/17744#deploy-anbox-cloud) +* {ref}`sec-deploy-anbox-cloud-juju` (installs streaming stack) * [Signalling](https://www.html5rocks.com/en/tutorials/webrtc/infrastructure/) -* [Supported codecs](https://discourse.ubuntu.com/t/37323) +* {ref}`ref-codecs` diff --git a/explanation/applications.md b/explanation/applications.md index 5d0df8a8..3ac093f9 100644 --- a/explanation/applications.md +++ b/explanation/applications.md @@ -1,14 +1,18 @@ +(exp-applications)= +# Applications + Applications are one of the main objects managed by Anbox Management Service (AMS). A single application encapsulates one Android APK ([Android Package Kit](https://en.wikipedia.org/wiki/Android_application_package)) and manages it within the cluster. It takes care of installing the supplied APK and making it available to users. AMS also manages updates to existing applications, which includes allowing the operator to test new uploaded versions before making them available to any users. ## Application requirements To run on the Anbox Cloud platform, applications must fulfil the following requirements: -* The application **SHOULD NOT** download any additional resources on regular startup to contribute to short startup times. If additional resources need to be downloaded, this can be done during the application bootstrap phase. -* The application **MUST NOT** require the **Google Play services** to be available as Anbox Cloud does not include them. +* The application *should not* download any additional resources on regular startup to contribute to short startup times. If additional resources need to be downloaded, this can be done during the application bootstrap phase. +* The application *must not* require the *Google Play services* to be available as Anbox Cloud does not include them. -If your application fulfils these requirements but you are still having issues running it on Anbox Cloud, file a [bug report](https://bugs.launchpad.net/indore-extern/+filebug). +If your application fulfils these requirements but you are still having issues running it on Anbox Cloud, file a [bug report](https://bugs.launchpad.net/anbox-cloud/+filebug). +(sec-application-status)= ## Possible application statuses The following table lists the different statuses that an application can have depending on its state and what each status means: @@ -21,16 +25,18 @@ The following table lists the different statuses that an application can have de | `error` | The application has encountered an error. | | `unknown` | A possible error occurred and the real state of the application cannot be determined. | -If you encounter the `error` or the `unknown` status, see if you can identify the base instance and troubleshoot using the instance logs (See [How to view the instance logs](https://discourse.ubuntu.com/t/how-to-view-the-instance-logs/24329)). If you are still unable to figure out the issue, [file a bug](https://bugs.launchpad.net/anbox-cloud) with the [relevant instance logs](https://discourse.ubuntu.com/t/how-to-view-the-instance-logs/24329#view-stored-logs-2). +If you encounter the `error` or the `unknown` status, see if you can identify the base instance and troubleshoot using the instance logs (See {ref}`howto-view-instance-logs`). If you are still unable to figure out the issue, [file a bug](https://bugs.launchpad.net/anbox-cloud) with the {ref}`relevant instance logs `. + +(sec-application-bootstrap)= ## Bootstrap process -When [creating an application](https://discourse.ubuntu.com/t/create-an-application/24198) from a directory, a tarball, or a zip archive, AMS will perform a bootstrap process, which builds the application and synchronises it across all LXD nodes in the cluster. There are major benefits that the bootstrap process provides: +When creating an application from a directory, a tarball, or a zip archive, AMS will perform a bootstrap process, which builds the application and synchronises it across all LXD nodes in the cluster. There are major benefits that the bootstrap process provides: * It enables AMS to launch an instance for an application without installing the APK every time. * It dramatically speeds up the startup time of a regular instance. -Furthermore, an application is synchronised within the LXD cluster, which enables AMS to continue to work when nodes are being removed from the cluster through [scaling down](https://discourse.ubuntu.com/t/scale-down-a-lxd-cluster/24323) or lost from the cluster unexpectedly. +Furthermore, an application is synchronised within the LXD cluster, which enables AMS to continue to work when nodes are being removed from the cluster through scaling down or lost from the cluster unexpectedly. A temporary base instance is created and used for bootstrapping during the application creation. For example, you might see the following output for `amc ls` right after creating an application: @@ -46,7 +52,7 @@ In general, the bootstrap process goes through the following steps in order: 1. Configure the network interface and gateway. 2. Apply any pending Ubuntu system security updates. -3. Install [addons](https://discourse.ubuntu.com/t/addons/25293) listed in the application manifest file. +3. Install addons listed in the application manifest file. 4. Run the `pre-start` hook provided by each addon listed in the application manifest. 5. Launch the Android container. 6. Install the APK provided by the application. @@ -86,18 +92,20 @@ error_message: 'Failed to install application: com.foo.bar: Failed to extract na config: {} ``` -Alternatively, [check the instance logs](https://discourse.ubuntu.com/t/24329) to troubleshoot problems in an instance. +Alternatively, {ref}`check the instance logs ` to troubleshoot problems in an instance. When the application bootstrap succeeds, the base instance is automatically removed and the status of the application changes to `ready` indicating that the application is ready to use. -## Related information - -* [Application manifest](https://discourse.ubuntu.com/t/application-manifest/24197) -* [How to create an application](https://discourse.ubuntu.com/t/create-an-application/24198) -* [How to wait for an application](https://discourse.ubuntu.com/t/wait-for-an-application/24202) -* [How to update an application](https://discourse.ubuntu.com/t/update-an-application/24201) -* [How to configure available resources](https://discourse.ubuntu.com/t/configure-available-resources/24960) -* [How to delete an application](https://discourse.ubuntu.com/t/delete-an-application/24199) -* [How to list applications](https://discourse.ubuntu.com/t/list-applications/24200) -* [How to test your application](https://discourse.ubuntu.com/t/usecase-application-testing/17775) -* [How to create a virtual device](https://discourse.ubuntu.com/t/virtual-devices/19069) +## Related topics + +* {ref}`exp-addons` +* {ref}`exp-resources-presets` +* {ref}`howto-create-virtual-device` +* {ref}`howto-create-application` +* {ref}`howto-delete-application` +* {ref}`howto-list-applications` +* {ref}`howto-scale-down-cluster` +* {ref}`howto-test-application` +* {ref}`howto-update-application` +* {ref}`howto-wait-for-application` +* {ref}`ref-application-manifest` diff --git a/explanation/capacity-planning.md b/explanation/capacity-planning.md index 17128d14..ec199299 100644 --- a/explanation/capacity-planning.md +++ b/explanation/capacity-planning.md @@ -1,3 +1,6 @@ +(exp-capacity-planning)= +# Capacity planning + When planning your Anbox Cloud deployment, you should start by estimating how much capacity you need, to be able to provide your application to your users and how many users (translating to the number of Android containers) you expect. Based on this estimate, you can then size your deployment and figure out how many cluster nodes you need and what resources they should have. When estimating capacity, consider the following questions to better understand your requirements: @@ -23,21 +26,24 @@ A default resource preset will be set for every application. A resource preset s - The amount of disk space - The number of GPU slots -Depending on the resources that your application requires, if the [default resource preset](https://discourse.ubuntu.com/t/24960) does not suit, you can choose suitable [resources](https://discourse.ubuntu.com/t/application-manifest/24197#resources-7) that fit your application. +Depending on the resources that your application requires, if the {ref}`default resource preset ` does not suit, you can choose suitable {ref}`sec-application-manifest-resources` that fit your application. -When an instance for an application is launched, it takes the specified amount of resources. AMS internally summarises the amount of resources used by instances on a single machine and disallows launching additional instances when all resources are used (see [Over-committing resources](#over-committing-resources-3) for how to allow a higher resource usage). In such cases, you will see the following error message when trying to launch a new instance: +When an instance for an application is launched, it takes the specified amount of resources. AMS internally summarises the amount of resources used by instances on a single machine and disallows launching additional instances when all resources are used (see [Over-committing resources](#over-committing-resources) for how to allow a higher resource usage). In such cases, you will see the following error message when trying to launch a new instance: No suitable node to satisfy instance requirement available If an instance stops with an error, its disk space is preserved for inspection. Other resources are released. Therefore, if you have many instances with `error` status, you might run out of disk space. +(sec-gpu-slots)= ### GPU slots -An additional aspect to take into account when planning your resources is the number of required GPU slots (see [GPUs and instances](https://discourse.ubuntu.com/t/17768) for more information). +An additional aspect to take into account when planning your resources is the number of required GPU slots (see {ref}`exp-gpus-instances` for more information). -[note type="information" status="Note"]Currently, Anbox Cloud does not have GPU support for virtual machines. This feature is planned for a future release.[/note] +```{note} +Currently, Anbox Cloud does not have GPU support for virtual machines. This feature is planned for a future release. +``` -GPUs have limited capacity that can be shared amongst multiple instances, and GPU slots are a way to fine-tune how many instances can run on a given node. In a cluster setup, you define the number of available GPU slots for each node (see [Configure GPU slots](https://discourse.ubuntu.com/t/configure-cluster-nodes/28716#configure-gpu-slots-and-gpu-encoder-slots-4) for instructions). +GPUs have limited capacity that can be shared amongst multiple instances, and GPU slots are a way to fine-tune how many instances can run on a given node. In a cluster setup, you define the number of available GPU slots for each node (see {ref}`sec-config-gpu-slots` for instructions). To determine the best number of GPU slots for a specific GPU model, consider the following aspects: @@ -45,19 +51,19 @@ To determine the best number of GPU slots for a specific GPU model, consider the - The memory that an instance uses - The number of parallel encoding pipelines that the GPU offers -When you launch an instance for an application, AMS reserves the number of GPU slots defined for the application on the node where it is launched. These GPU slots are marked as unavailable until the instance is terminated. If no GPU slots are available on the node, instances that require a GPU ([video encoder type](https://discourse.ubuntu.com/t/application-manifest/24197#video-encoder-4) `gpu`) will not be launched on it. Instances that don't require a GPU ([video encoder type](https://discourse.ubuntu.com/t/application-manifest/24197#video-encoder-4) `software` or `gpu-preferred`) can still be launched. +When you launch an instance for an application, AMS reserves the number of GPU slots defined for the application on the node where it is launched. These GPU slots are marked as unavailable until the instance is terminated. If no GPU slots are available on the node, instances that require a GPU (with video encoder type as `gpu`) will not be launched on it. Instances that don't require a GPU (with video encoder type as `software` or `gpu-preferred`) can still be launched. See {ref}`sec-application-manifest-video-encoder` for more information on video encoder types. -[note type="information" status="Important"] +```{important} GPU slots are used to share GPUs amongst instances, but they do not impose limits on GPU usage. Therefore, increasing the number of required GPU slots for an application does not guarantee that more GPU resources are allocated to the corresponding application instances. For example, an intensive game that is configured to use one GPU slot might consume more GPU resources than a simple photo gallery app that is configured to use five GPU slots. The main purpose of GPU slots is to control the number of instances that are launched on a node that has a GPU installed, which reduces contention for GPU resources. -[/note] - +``` +(sec-over-committing)= ## Over-committing resources If the unused resources on a cluster node don't suffice to launch an instance for an application with its defined resource requirements, the instance cannot be launched. This behaviour is very restrictive, and in many cases unnecessary. -Usually, an instance doesn't use its dedicated vCPU cores and memory at 100% all the time. Therefore, AMS allows over-committing available resources. By default, AMS uses a CPU allocation rate of `4` and a memory allocation rate of `2`, which means that it allows four times the number of vCPU cores and twice the amount of RAM per node. See [Configure allocation rates](https://discourse.ubuntu.com/t/configure-cluster-nodes/28716#configure-allocation-rates-2) for instructions on how to define the allocation rates for a node. +Usually, an instance doesn't use its dedicated vCPU cores and memory at 100% all the time. Therefore, AMS allows over-committing available resources. By default, AMS uses a CPU allocation rate of `4` and a memory allocation rate of `2`, which means that it allows four times the number of vCPU cores and twice the amount of RAM per node. See {ref}`sec-config-allocation-rates` for instructions on how to define the allocation rates for a node. For example, consider an application that has a resource preset of 2 vCPU cores and 3 GB of memory, and you have a node with 8 CPU cores and 16 GB of memory. Without over-commitment, you could only launch four instances before you run out of resources on the node. However, with a CPU allocation rate of `4` and a memory allocation rate of `2` (the default), the available resources on the node change to `4 * 8 physical CPU cores = 32 vCPU cores` and `2 * 16 GB memory = 32 GB memory`, which will allow up to ten instances on the node. @@ -67,7 +73,9 @@ The CPU allocation rate depends on the type of application and the amount of res To realistically estimate the required capacity for your deployment, you must consider the type of application that you're running and the expected usage behaviour. -You should [run benchmarks](https://discourse.ubuntu.com/t/how-to-run-benchmarks/17770) to test your application performance and fine-tune the best node and application configuration. Also consider whether your instances use a hardware or software [video encoder](https://discourse.ubuntu.com/t/application-manifest/24197#video-encoder-4) for video encoding, and the frame rate and resolution they require. +You should run benchmarks to test your application performance and fine-tune the best node and application configuration. See {ref}`howto-run-benchmarks`. + +Also consider whether your instances use a hardware or software video encoder for video encoding, and the frame rate and resolution they require. Another aspect is, of course, the number of users expected and hence, the number of instances that will be running simultaneously. If you expect the usage to be rather consistent, you might not need to plan for huge peaks in load. On the other hand, you must also consider the impact if your cluster runs out of resources and it is not possible anymore to start more instances. @@ -98,9 +106,14 @@ The current calculation does not take into account that there might be peaks of - Disk space: `200 * 3 GB = 600 GB` - GPU slots: `200 * 1 = 200` -To avoid your cluster running out of resources even at peak loads, you must size it accordingly (or dynamically scale it up and down, see [About clustering](https://discourse.ubuntu.com/t/about-clustering/17765)). If the impact of not being able to provide additional instances at peak loads is rather low, you could compromise on the following factors: +To avoid your cluster running out of resources even at peak loads, you must size it accordingly (or dynamically scale it up and down). If the impact of not being able to provide additional instances at peak loads is rather low, you could compromise on the following factors: - Use a higher CPU and/or memory allocation rate, which might decrease performance at peak loads. - Configure your cluster nodes to use more GPU slots per GPU, which might decrease video quality. - Tweak the resource preset for your application to give less resources to each instance. The impact of doing this depends very much on your application. - Base your estimate on a lower maximum number of instances (for example, 150 instances), which will lead to your cluster running out of resources before the peak load is reached. + +## Related topics + +* {ref}`exp-clustering` +* {ref}`ref-application-manifest` \ No newline at end of file diff --git a/explanation/clustering.md b/explanation/clustering.md index 6337b955..19f0b9f6 100644 --- a/explanation/clustering.md +++ b/explanation/clustering.md @@ -1,3 +1,6 @@ +(exp-clustering)= +# Clustering + While it is possible to install Anbox Cloud on a single machine, Anbox Cloud Appliance does not support multi-node setups. If you intend to distribute the load across multiple machines in a cluster, it is recommended to use Anbox Cloud for full deployments instead. ## Clustering for full Anbox Cloud deployments @@ -8,8 +11,9 @@ Each worker node runs [LXD](https://ubuntu.com/lxd) in [clustering mode](https:/ ### Cluster capacity -Anbox Cloud is optimised to provide instances at high density per host. To determine how many cluster nodes you need and what resources they should have, you must estimate the capacity that you require for your use case. See [About capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) for more information. +Anbox Cloud is optimised to provide instances at high density per host. To determine how many cluster nodes you need and what resources they should have, you must estimate the capacity that you require for your use case. See {ref}`exp-capacity-planning` for more information. +(sec-lxd-auto-scaling)= ### LXD auto scaling Different use cases for Anbox Cloud require elasticity of the LXD cluster to deal with dynamic user demand throughout a certain time period. This involves increasing the number of nodes of the LXD cluster when demand increases and reducing the number of nodes when demand decreases. As Anbox Cloud provides fine-grained capacity management to have tight control over how many users/instances are running on a single node, the driving factor for an auto scaling implementation cannot be deduced from CPU, memory or GPU load but from the planned capacity of the currently available nodes in the cluster. @@ -31,12 +35,12 @@ The following guidelines are both recommended and must-have aspects of an auto s The decision of when to scale a cluster up or down is not simple and is different for each use case. The traditional approach to measure CPU, memory or GPU load does not apply for Anbox Cloud as capacity is well-planned and the number of instances per node is configured ahead of time. Furthermore, user patterns are hard to predict and will be different in each case. Hence, custom logic is required to take a decision when a cluster should be scaled up or down. -Anbox Cloud provides [various metrics](https://discourse.ubuntu.com/t/prometheus-metrics/19521) to help decide when to scale up or down. Based on these metrics, together with data from a production system, you can build a model trying to predict when auto scaling should trigger. +Anbox Cloud provides various metrics to help decide when to scale up or down. Based on these metrics, together with data from a production system, you can build a model trying to predict when auto scaling should trigger. See {ref}`ref-prometheus-metrics` for more information. Future versions of Anbox Cloud will provide a framework which will help to implement such a model. -See [How to scale up a LXD cluster](https://discourse.ubuntu.com/t/scale-up-a-lxd-cluster/24322) and [How to scale down a LXD cluster](https://discourse.ubuntu.com/t/scale-down-a-lxd-cluster/24323) for instructions on how to add or remove nodes from the cluster. +See {ref}`howto-scale-up-cluster` and {ref}`howto-scale-down-cluster` for instructions on how to add or remove nodes from the cluster. -## Related information +## Related topics -* [Manage cluster nodes](https://discourse.ubuntu.com/t/how-to-manage-cluster-nodes/24334) +* {ref}`howto-manage-cluster` diff --git a/explanation/custom-images.md b/explanation/custom-images.md index 375c277f..e33664b1 100644 --- a/explanation/custom-images.md +++ b/explanation/custom-images.md @@ -1,6 +1,11 @@ +(exp-custom-images)= +# Custom images + Building custom images of Anbox Cloud based on AAOS is possible but is not recommended. -[note type="information" status="Note"]Building custom images is possible only for Android 13 and is currently possible for AAOS images only.[/note] +```{note} +Building custom images is possible only for Android 13 and is currently possible for AAOS images only. +``` Using customised Anbox Cloud images will lead to more maintenance work on your end: diff --git a/explanation/gpus-instances.md b/explanation/gpus-instances.md index 86628d39..e805b03f 100644 --- a/explanation/gpus-instances.md +++ b/explanation/gpus-instances.md @@ -1,32 +1,40 @@ +(exp-gpus-instances)= +# GPUs and instances + Anbox Cloud has support for managing GPUs and can provide them to individual instances for rendering and video encoding functionality. -[note type="information" status="Important"]This topic is applicable only for container instances because Anbox Cloud currently does not support GPU provisioning for virtual machines. This feature is planned for a future release.[/note] +```{important} +This topic is applicable only for container instances because Anbox Cloud currently does not support GPU provisioning for virtual machines. This feature is planned for a future release. +``` + +Anbox Cloud automatically detects GPU devices during the deployment and configures the cluster to use them. If no GPU is available, Anbox Cloud automatically falls back to the `null` platform that does not perform any rendering. See {ref}`sec-null-platform` for the `null` platform configuration. -Anbox Cloud automatically detects GPU devices during the deployment and configures the cluster to use them. If no GPU is available, Anbox Cloud automatically falls back to the [`null` platform](https://discourse.ubuntu.com/t/anbox-platforms/18733) that does not perform any rendering. However, you can enable software rendering and video encoding by launching your application with the `--enable-graphics` flag. This makes it possible to run entirely without a GPU and still use rendering. +However, you can enable software rendering and video encoding by launching your application with the `--enable-graphics` flag. This makes it possible to run entirely without a GPU and still use rendering. ## Required GPU slots GPUs have limited capacity that can be shared amongst multiple instances. To fine-tune how many instances can run on a given node, configure the number of available GPU slots on the node. -See [GPU slots](https://discourse.ubuntu.com/t/about-capacity-planning/28717#gpu-slots-2) for detailed information. +See {ref}`sec-gpu-slots` for detailed information. ## Using GPUs inside an instance AMS configures each LXD instance to pass through a GPU device from the host. Currently, all GPUs that are available to a machine are passed to every instance that owns a GPU slot. For NVIDIA GPUs, LXD uses the [NVIDIA container runtime](https://github.com/NVIDIA/nvidia-container-runtime) to make the GPU driver of the host available to the instance. -Check the [list of supported GPUs](https://discourse.ubuntu.com/t/37322#supported-gpu-vendors-and-gpu-models-1) to see if Anbox Cloud includes a driver for your GPU device. If a GPU driver is available inside the instance, there are no further differences in how to use it in comparison to a regular environment. If no GPU driver is available, you must provide it through an [addon](https://discourse.ubuntu.com/t/managing-addons/17759). +Check the list of supported GPUs ({ref}`sec-supported-gpus`) to see if Anbox Cloud includes a driver for your GPU device. If a GPU driver is available inside the instance, there are no further differences in how to use it in comparison to a regular environment. If no GPU driver is available, you must provide it through an addon. If you want to let an application use the GPU (even if you are not interested in streaming the visual output), launch it with the `--enable-graphics` flag. With this flag, the command will launch the instance using the `webrtc` platform, which will automatically detect the underlying GPU and make use of it. amc launch --enable-graphics my-application - +(sec-sw-rendering-video-encoding)= ## Force software rendering and video encoding -It is possible to instruct an instance to run with software rendering. To do so, change the [resources](https://discourse.ubuntu.com/t/application-manifest/24197#resources-7) of the application to not require a GPU. Anbox Cloud will then automatically determine that no GPU is available and use software rendering instead if an instance is launched with graphics enabled. +It is possible to instruct an instance to run with software rendering. To do so, change the {ref}`sec-application-manifest-resources` of the application to not require a GPU. Anbox Cloud will then automatically determine that no GPU is available and use software rendering instead if an instance is launched with graphics enabled. Since software rendering and video encoding will utilise the CPU, you won't be able to run as many instances on a system when compared to running instances with a GPU. -## Related information -* [Supported rendering resources](https://discourse.ubuntu.com/t/37322) - +## Related topics +* {ref}`exp-addons` +* {ref}`ref-application-manifest` +* {ref}`ref-rendering-resources` diff --git a/explanation/images.md b/explanation/images.md index 0c4c0220..37d2792b 100644 --- a/explanation/images.md +++ b/explanation/images.md @@ -1,3 +1,6 @@ +(exp-images)= +# Images + An image represents the Anbox Cloud image available in the AMS node. An image is the base for an instance, which contains all necessary components like Anbox or the Android root file system. The image type can be container or virtual machine. # Possible image statuses diff --git a/explanation/instances.md b/explanation/instances.md index dd4d5b3e..1803cbae 100644 --- a/explanation/instances.md +++ b/explanation/instances.md @@ -1,24 +1,27 @@ +(exp-instances)= +# Instances + Instances are the centre piece of the Anbox Cloud stack. Every time you launch an application or an image, Anbox Cloud creates an instance for it. Every instance provides a full Android system. -All instances in Anbox Cloud are ephemeral, which means that as soon as an instance is stopped, all of its data is deleted. Anbox Cloud **DOES NOT** back up any data from the Android or the outer Ubuntu instance. Backup and restore of data must be implemented separately through [addons](https://discourse.ubuntu.com/t/addons/25293). See [Example: Back up data](https://discourse.ubuntu.com/t/example-back-up-data/25289) for information on how to do this. +All instances in Anbox Cloud are ephemeral, which means that as soon as an instance is stopped, all of its data is deleted. Anbox Cloud **DOES NOT** back up any data from the Android or the outer Ubuntu instance. Backup and restore of data must be implemented separately through addons. See {ref}`howto-backup-restore-example` for information on how to do this. - +(sec-regular-base-instances)= ## Regular instances vs. base instances Anbox Cloud differentiates between two types of instances: regular and base. The instance type is visible in the output of the `amc ls` command. Regular instances are containers or virtual machines that are launched from either an application or an image. They exist until they are deleted. -Base instances are temporary containers or virtual machines that are used when [bootstrapping an application](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2). They are automatically deleted when the application bootstrap is completed. +Base instances are temporary containers or virtual machines that are used when bootstrapping an application. They are automatically deleted when the application bootstrap is completed. See {ref}`sec-application-bootstrap` for more information on the bootstrapping process. When we refer to instances in this documentation without specifying the instance type, we mean regular instances. - +(sec-application-raw-instances)= ## Application instances vs. raw instances -Instances are based on either [applications](https://discourse.ubuntu.com/t/managing-applications/17760) or [images](https://discourse.ubuntu.com/t/provided-images/24185). So if you launch an application or an image, Anbox Management Service (AMS) automatically creates an instance for it. +Instances are based on either {ref}`exp-applications` or {ref}`Images `. So if you launch an application or an image, Anbox Management Service (AMS) automatically creates an instance for it. -Application instances are containers or virtual machines created when launching an application and run the full Android system. If the application is based on an Android app (an APK package), this app is launched after the system boots and monitored by the [watchdog](https://discourse.ubuntu.com/t/application-manifest/24197#watchdog-5). With the default configuration, you will see only the app and not the Android launcher. +Application instances are containers or virtual machines created when launching an application and run the full Android system. If the application is based on an Android app (an APK package), this app is launched after the system boots and monitored by the {ref}`sec-application-manifest-watchdog`. With the default configuration, you will see only the app and not the Android launcher. Raw instances are containers or virtual machines created when launching an image. They run the full Android system, without any additional apps installed. @@ -26,7 +29,7 @@ Raw instances are containers or virtual machines created when launching an image ### Creating an instance -When you [create an instance](https://discourse.ubuntu.com/t/24327) by either launching or initialising an application or an image, AMS schedules the instance on a LXD node. The instance then executes the following steps in order: +When you create an instance by either launching or initialising an application or an image, AMS schedules the instance on a LXD node. The instance then executes the following steps in order: 1. Configure the network interface and gateway. 1. (Only for raw instances) Install addons that are specified with `--addons`. @@ -37,7 +40,7 @@ When you [create an instance](https://discourse.ubuntu.com/t/24327) by either la ![Instance start|584x646](https://assets.ubuntu.com/v1/45389cab-instance_start.png) -Launching an instance is successful only if all of the above steps succeed. If there are issues during the process, the status of the instance changes to `error`. You can [view the available logs](https://discourse.ubuntu.com/t/24329) from the instance for further troubleshooting. +Launching an instance is successful only if all of the above steps succeed. If there are issues during the process, the status of the instance changes to `error`. You can view the available logs from the instance for further troubleshooting. See {ref}`howto-view-instance-logs`. ### Stopping an instance @@ -71,27 +74,29 @@ An instance moves through different stages and correspondingly can have the foll | `error` | An error occurred while processing the instance. The instance is stopped. | | `unknown` | A possible error occurred and the real state of the instance cannot be determined. | -If you encounter the `error` or the `unknown` status, use [`amc show `](https://discourse.ubuntu.com/t/amc-command-reference-show/40793) or [`amc-showlog`](https://discourse.ubuntu.com/t/amc-command-reference-show-log/40792) to troubleshoot. If you are still unable to figure out the issue, [file a bug](https://bugs.launchpad.net/anbox-cloud) with the [relevant instance logs](https://discourse.ubuntu.com/t/how-to-view-the-instance-logs/24329#view-stored-logs-2). +If you encounter the `error` or the `unknown` status, use [`amc show `](/reference/cmd-ref/amc-command-reference/show.md) or [`amc-showlog`](/reference/cmd-ref/amc-command-reference/show-log.md) to troubleshoot. If you are still unable to figure out the issue, [file a bug](https://bugs.launchpad.net/anbox-cloud) with the {ref}`relevant instance logs `. - +(sec-dev-mode)= ## Development mode AMS allows to start an instance in development mode. This mode turns off some features that are usually active in an instance. It is mainly useful when developing addons inside an instance. -When development mode is enabled, the instance sends status updates to AMS when the Anbox runtime is terminated, however, AMS allows the instance to continue running. This allows you to restart the Anbox runtime inside the instance, providing an easy way to test [addons](https://discourse.ubuntu.com/t/addons/25293) or develop a [platform plugin](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/). +When development mode is enabled, the instance sends status updates to AMS when the Anbox runtime is terminated, however, AMS allows the instance to continue running. This allows you to restart the Anbox runtime inside the instance, providing an easy way to test addons or develop a platform plugin. To check whether development mode is enabled, run `amc show ` or look at the `/var/lib/anbox/session.yaml` file in the instance. If the `devmode` field in the configuration file is set to `true`, development mode is active. -## Related information - - * [How to create an instance](https://discourse.ubuntu.com/t/24327) - * [How to start an instance](https://discourse.ubuntu.com/t/33924) - * [How to wait for an instance](https://discourse.ubuntu.com/t/24330) - * [How to access an instance](https://discourse.ubuntu.com/t/17772) - * [How to expose services on an instance](https://discourse.ubuntu.com/t/24326) - * [How to view the instance logs](https://discourse.ubuntu.com/t/24329) - * [How to stop an instance](https://discourse.ubuntu.com/t/33925) - * [How to delete an instance](https://discourse.ubuntu.com/t/24325) - * [How to list instances](https://discourse.ubuntu.com/t/24328) - * [How to configure geographic location](https://discourse.ubuntu.com/t/17782) - * [How to back up and restore application data](https://discourse.ubuntu.com/t/24183) +## Related topics + +* {ref}`exp-addons` +* [Platform plugin](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/) +* {ref}`howto-access-instance` +* {ref}`howto-backup-restore-application-data` +* {ref}`howto-create-instance` +* {ref}`howto-configure-geographic-location` +* {ref}`howto-delete-instance` +* {ref}`howto-expose-services` +* {ref}`howto-list-instances` +* {ref}`howto-start-instance` +* {ref}`howto-stop-instance` +* {ref}`howto-view-instance-logs` +* {ref}`howto-wait-for-application` diff --git a/explanation/landing.md b/explanation/landing.md index e164d93d..c9a4b328 100644 --- a/explanation/landing.md +++ b/explanation/landing.md @@ -1,3 +1,6 @@ +(explanation)= +# Explanation + The explanatory and conceptual guides in this section provide a better understanding of Anbox Cloud and enable you to get the most out of it. ## Anbox Cloud: Architecture and components @@ -5,32 +8,59 @@ The explanatory and conceptual guides in this section provide a better understan Understand the underlying architecture of Anbox Cloud, its variants and how the different components of Anbox Cloud relate to each other | Guides | What they explain | |--|--| -| [Anbox Cloud](https://discourse.ubuntu.com/t/17802) | Differences between Anbox Cloud and the Anbox Cloud Appliance, explanation about the components and architecture of the offering | -| [AMS](https://discourse.ubuntu.com/t/24321)| The Anbox Management Service (AMS) and how it handles aspects of the application and life cycle of an instance | -| [AAR](https://discourse.ubuntu.com/t/17761)| The Anbox Application Registry (AAR) and what it does| -| [Application streaming](https://discourse.ubuntu.com/t/17769)| Architecture of the Streaming Stack and supported video codecs | -| [Rendering architecture](https://discourse.ubuntu.com/t/35129)| Different rendering pipelines for supported GPUs | +| {ref}`exp-anbox-cloud` | Differences between Anbox Cloud and the Anbox Cloud Appliance, explanation about the components and architecture of the offering | +| {ref}`exp-ams` | The Anbox Management Service (AMS) and how it handles aspects of the application and life cycle of an instance | +| {ref}`exp-aar` | The Anbox Application Registry (AAR) and what it does| +| {ref}`exp-application-streaming` | Architecture of the Streaming Stack and supported video codecs | +| {ref}`exp-rendering-architecture` | Different rendering pipelines for supported GPUs | ## Working with Anbox Cloud Understand the different objects used in the product stack and how to use them to tune the performance of Anbox Cloud. | Guides | What they explain | |--|--| -| [Applications](https://discourse.ubuntu.com/t/17760)| Application requirements and the application bootstrap process | -| [Instances](https://discourse.ubuntu.com/t/17763)| Learn about an instance and its life cycle | -| [Platforms](https://discourse.ubuntu.com/t/configuration-for-supported-platforms/18733)| Configuring supported platforms | -| [Clustering](https://discourse.ubuntu.com/t/17765)| Clustering and managing the load over multiple machines| -| [Performance](https://discourse.ubuntu.com/t/29416) | Aspects that are relevant for tuning the performance of Anbox Cloud | +| {ref}`exp-applications` | Application requirements and the application bootstrap process | +| {ref}`exp-instances` | Learn about an instance and its life cycle | +| {ref}`exp-platforms` | Configuring supported platforms | +| {ref}`exp-clustering` | Clustering and managing the load over multiple machines| +| {ref}`exp-performance` | Aspects that are relevant for tuning the performance of Anbox Cloud | ## Deploying Anbox Cloud Understand deployment configurations to plan your deployment. | Guides | What they explain | |--|--| -| [Production planning](https://discourse.ubuntu.com/t/34648) | Aspects to consider for best results when you are planning a production deployment | -| [Capacity planning](https://discourse.ubuntu.com/t/28717) | How to estimate the required capacity for your Anbox Cloud deployment | -| [GPUs and instances](https://discourse.ubuntu.com/t/17768)| How to manage GPUs and make them available to instances | -| [Security](https://discourse.ubuntu.com/t/31217)| Important aspects to keep your Anbox Cloud deployment secure | +| {ref}`exp-production-planning` | Aspects to consider for best results when you are planning a production deployment | +| {ref}`exp-capacity-planning` | How to estimate the required capacity for your Anbox Cloud deployment | +| {ref}`exp-gpus-instances` | How to manage GPUs and make them available to instances | +| {ref}`exp-security` | Important aspects to keep your Anbox Cloud deployment secure | +| {ref}`exp-custom-images` | Learn about customising AAOS images | + + +Also check out the {ref}`tutorials` for step-by-step instructions that help you get familiar with Anbox Cloud, the {ref}`how-to-guides` for instructions on how to achieve specific goals when using Anbox Cloud and the {ref}`reference` section for reference material. +```{toctree} +:hidden: -Also check out the [Tutorials](https://discourse.ubuntu.com/t/tutorials/28826) for step-by-step instructions that help you get familiar with Anbox Cloud, the [How-to guides](https://discourse.ubuntu.com/t/how-to-guides/28827) for instructions on how to achieve specific goals when using Anbox Cloud and the [Reference](https://discourse.ubuntu.com/t/reference/28828) section for reference material. +addons +aar +anbox-cloud +web-dashboard +ams +aaos +applications +application-streaming +capacity-planning +clustering +custom-images +gpus-instances +images +instances +nodes +performance +production +rendering-architecture +resources +security +platforms +``` diff --git a/explanation/nodes.md b/explanation/nodes.md index f51761de..14dcdfaa 100644 --- a/explanation/nodes.md +++ b/explanation/nodes.md @@ -1,3 +1,6 @@ +(exp-nodes)= +# Nodes + A node is a machine in the LXD cluster. Depending on whether it is running the management components of Anbox Cloud or streaming services, the node can serve multiple purposes such as a control node, worker node etc. The Anbox Management Service(AMS) hosts metadata that is necessary for its functioning on the nodes. # Possible node statuses diff --git a/explanation/performance.md b/explanation/performance.md index deae02a6..acac1a4e 100644 --- a/explanation/performance.md +++ b/explanation/performance.md @@ -1,27 +1,26 @@ +(exp-performance)= +# Performance + The performance of your Anbox Cloud deployment depends on multiple factors. To ensure optimal performance, check and monitor all areas and tune your deployment based on your findings. -To measure the performance based on different parameters, you should [run performance benchmarks](https://discourse.ubuntu.com/t/how-to-run-benchmarks/17770). See the provided [Performance benchmarks](https://discourse.ubuntu.com/t/performance-benchmarks/24709) as a reference for what performance you can expect with different hardware configurations. +To measure the performance based on different parameters, you should run performance benchmarks. See {ref}`howto-run-benchmarks` for more information on how to run performance benchmarks. -The main areas for performance tuning are: +See the provided {ref}`ref-performance-benchmarks` as a reference for what performance you can expect with different hardware configurations. -- [Instance density](#instance-density) -- [CPU access for an instance](#instance-cpu-access) -- [Hardware and network setup](#hardware-setup) -- [Startup time for an instance](#startup-time) -- [Client devices](#client-devices) +The main areas for performance tuning are detailed in this guide. - +(sec-instance-density)= ## Instance density The most apparent performance aspect is how many instances you can run on each of your machines. -Of course, the instance density depends a lot on the available hardware. See [capacity planning information](https://discourse.ubuntu.com/t/about-capacity-planning/28717) to estimate the necessary capacity and the hardware requirements for your Anbox Cloud deployment. +Of course, the instance density depends a lot on the available hardware. See {ref}`exp-capacity-planning` to estimate the necessary capacity and the hardware requirements for your Anbox Cloud deployment. In addition, check your applications and make sure they use the resources in a fair way. Applications should avoid spikes in GPU utilisation, because such spikes require the application to reserve more resources and therefore reduce the instance density. Generally, applications should use the smallest suitable resource preset. However, if you see an overall bad performance when running the application, using a more powerful resource preset usually helps (even though it reduces the instance density). As an example, consider an application that runs on an Anbox Cloud deployment that does not have any GPUs installed. In this case, the rendering workload is put on the CPU instead of the GPU, and if the resource preset of the application does not have a sufficient number of vCPU cores, the performance of the application is impacted. This can show, for example, in the virtual keyboard being really slow. By switching to a more powerful resource preset, the instance density is reduced, but the performance of each application instance is increased. - +(sec-instance-cpu-access)= ## CPU access for an instance AMS has different modes to grant CPU access to an instance. The `cpu.limit_mode` configuration option can be used to change the mode. The possible modes are: @@ -37,18 +36,18 @@ AMS has different modes to grant CPU access to an instance. The `cpu.limit_mode` By default, AMS uses the `scheduler` option, because it provides the most generic solution to a large set of use cases that Anbox Cloud supports. However, in some cases CPU pinning might be the better option to distribute load across all available CPU cores on a system. - +(sec-hardware-network-setup)= ## Hardware and network setup -See [Requirements](https://discourse.ubuntu.com/t/installation-requirements/17734) for the minimum hardware requirements for Anbox Cloud. Note that these list the minimum requirements, and using more powerful hardware will increase performance. +See {ref}`ref-requirements` for the minimum hardware requirements for Anbox Cloud. Note that these list the minimum requirements, and using more powerful hardware will increase performance. -For optimal performance, you should use a dedicated block device for LXD storage. Using a loop file is considerably slower. See [LXD storage](https://discourse.ubuntu.com/t/anbox-cloud-overview/17802#lxd-storage-6) for more information. +For optimal performance, you should use a dedicated block device for LXD storage. Using a loop file is considerably slower. See {ref}`sec-lxd-storage` for more information. The overall performance depends not only on the hardware used for the actual Anbox Cloud deployment, but also on the setup used for other components that Anbox Cloud relies on. For example, the etcd database must use a hard disk that is fast enough. See [Hardware recommendations](https://etcd.io/docs/v3.5/op-guide/hardware/) for detailed information. Also make sure that there is a stable network connection between the nodes of your cluster, to decrease the latency between nodes. - +(sec-instance-startup-time)= ## Startup time for an instance A very noticeable performance issue is a long wait time when starting an application. @@ -59,7 +58,7 @@ Another configuration that affects the instance startup time is [shiftfs_enabled You should also check the hooks that you use in your application. If you use any startup hooks (`pre-start` or `post-start`) that take a long time or wait for resources to become available, the instance startup is delayed. If you use a `post-stop` hook that prolongs the shutdown of an instance, this might also affect the startup time of new instances (because it might not be possible to start more instances until the existing instances terminate). - +(sec-client-devices)= ## Client devices In addition to optimising the performance of your Anbox Cloud deployment, you must also make sure that the client devices that access it can fully utilise its capabilities. @@ -70,7 +69,9 @@ Furthermore, the network connection is crucial. When implementing your applicati Also make sure to optimise the network path from the Anbox Cloud server to the client devices. This optimisation could be very specific to your use case. For public clouds, it often means choosing the region that is located closest to the end users. When using a bare metal installation, you should deploy servers that are geographically close to the end users. There might also be other solutions depending on the network service route. -## Related information -* [Hooks](https://discourse.ubuntu.com/t/28555) -* [Instance benchmarks](https://discourse.ubuntu.com/t/17770#run-instance-benchmarks-1) -* [Capacity planning](https://discourse.ubuntu.com/t/28717) +## Related topics + +* {ref}`exp-capacity-planning` +* {ref}`howto-run-benchmarks` +* {ref}`ref-hooks` + diff --git a/explanation/platforms.md b/explanation/platforms.md index 7d1a9f2f..a2ca6345 100644 --- a/explanation/platforms.md +++ b/explanation/platforms.md @@ -1,12 +1,17 @@ +(exp-platforms)= +# Supported platforms + Anbox Cloud currently supports the `swrast`, `null`, `webrtc` platforms. This guide covers the display settings configuration for these platforms. -To instruct an [instance](https://discourse.ubuntu.com/t/26204#instance) to use a platform, include the `--platform` (or `-p`) flag when launching the instance: +To instruct an instance to use a platform, include the `--platform` (or `-p`) flag when launching the instance: amc launch -p webrtc ## Configuration for `swrast` platform -[note type="caution" status="Warning"]The `swrast` platform is deprecated and has been replaced with the `webrtc` platform starting with Anbox Cloud 1.13. You can still explicitly specify `swrast` as platform name, but internally, it is mapped to the `webrtc` platform. The `webrtc` platform provides backward compatibility with the display settings described below.[/note] +```{caution} +The `swrast` platform is deprecated and has been replaced with the `webrtc` platform starting with Anbox Cloud 1.13. You can still explicitly specify `swrast` as platform name, but internally, it is mapped to the `webrtc` platform. The `webrtc` platform provides backward compatibility with the display settings described below. +``` Anbox Cloud provides a way of add user data to the Android container upon its launch which can configure the display settings for `swrast` platform. @@ -29,6 +34,7 @@ The first two fields which imply display width and display height respectively a Then the specified display setting will be applied after the instance gets started. +(sec-null-platform)= ## Configuration for `null` platform Display settings for the `null` platform can be configured in the same way as for the `swrast` platform. @@ -50,6 +56,6 @@ For example, to configure the platform for a display height of 1080p and 60 FPS, amc launch -p webrtc --userdata '{"display_width":1920, "display_height":1080, "fps": 60}' -## Related information +## Related topics -* [Supported platforms](https://discourse.ubuntu.com/t/37322#supported-platforms-3) +* {ref}`exp-platforms` diff --git a/explanation/production.md b/explanation/production.md index f792672a..1fa6e169 100644 --- a/explanation/production.md +++ b/explanation/production.md @@ -1,14 +1,17 @@ +(exp-production-planning)= +# Production planning + When you are planning a production deployment, you should consider the aspects that you want to customise for best results. This topic covers the most common and important requirements when you are planning to move your Anbox Cloud deployment to production. While there could be other specifically tailored needs, this topic helps you identify your basic requirements and deployment strategy. ## Compute resource requirements -Depending on your workload and the type of deployment you choose, hardware or cloud resource requirements can differ. See [requirements](https://discourse.ubuntu.com/t/requirements/17734) to get an idea about the kind of resources that are required to run a full Anbox Cloud deployment with the streaming stack or a minimal core version of the deployment without the streaming stack. +Depending on your workload and the type of deployment you choose, hardware or cloud resource requirements can differ. See {ref}`ref-requirements` to get an idea about the kind of resources that are required to run a full Anbox Cloud deployment with the streaming stack or a minimal core version of the deployment without the streaming stack. You should pay special attention to the hardware requirements of applications that are used but not maintained by Anbox Cloud. ## Software requirements -Anbox Cloud deployments require the Ubuntu operating system. You should consider the Ubuntu OS, LXD, and Juju versions supported by Anbox Cloud for a production deployment. See [requirements](https://discourse.ubuntu.com/t/requirements/17734) to see compatible software versions. +Anbox Cloud deployments require the Ubuntu operating system. You should consider the Ubuntu OS, LXD, and Juju versions supported by Anbox Cloud for a production deployment. See {ref}`ref-requirements` to see compatible software versions. ## Networking requirements @@ -18,17 +21,17 @@ Consider the following questions to decide your networking requirements: * Do you need subnets? If yes, what is the range of the subnets that you want to define? * Do you require a virtual network and plan Juju spaces on top of it? * Where is your Anbox Application Registry (AAR) deployed? How will the AMS in other clusters connect to AAR? Define any peering requirements that you may have, based on the number of clusters you have and where AAR is deployed. To know more about AAR, see the following links: - * [Anbox Application Registry](https://discourse.ubuntu.com/t/anbox-application-registry-aar/17761) - * [How to deploy an AAR](https://discourse.ubuntu.com/t/how-to-deploy-an-aar/17749) - * [How to configure an AAR](https://discourse.ubuntu.com/t/how-to-configure-an-aar/24319) + * {ref}`exp-aar` + * {ref}`howto-deploy-aar` + * {ref}`howto-configure-aar` ## Storage requirements Based on your safety protocols, think about where you would want to host your storage. Also, refer to the following links that will help you plan and calculate your storage needs: -* [Requirements](https://discourse.ubuntu.com/t/requirements/17734) +* {ref}`ref-requirements` * [etcd recommendations](https://etcd.io/docs/v3.5/op-guide/hardware/) -* [Capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) +* {ref}`exp-capacity-planning` ## Scalability, High availability, and redundancy @@ -36,7 +39,7 @@ With Anbox Cloud, you can scale your deployment to as many clusters and subclust You should also assess the number of instances that you require for each model/service. For example, think about the number of Juju controller instances that you need. See [Make a controller highly available](https://juju.is/docs/olm/manage-controllers#heading--make-a-controller-highly-available) for more information. -Anbox Cloud comes with support for High Availability (HA) for both Core and the Streaming Stack.You can define HA by adding new Juju units. See [How to enable High availability?](https://discourse.ubuntu.com/t/how-to-enable-high-availability/17754) to plan your HA requirements. +Anbox Cloud comes with support for High Availability (HA) for both Core and the Streaming Stack. You can define HA by adding new Juju units. See {ref}`howto-enable-ha` to plan your HA requirements. ## Security @@ -46,13 +49,13 @@ Consider the following security aspects when you are planning for a production d Communication between the Anbox Cloud components uses TLS encryption and authentication. Access is controlled through secure authentication tokens or temporary passwords. Secure communication is achieved using TLS and public-key encryption with a chain of trust up to a shared root Certificate Authority (CA). However, when the cluster is being brought up or a new unit is being added, the chain of trust and certificates required must be bootstrapped into the machines. -See [About Security](https://discourse.ubuntu.com/t/about-security/31217) for more information. +See {ref}`exp-security` for more information. ### Patching You should keep your Anbox deployment updated to the latest available stable version. You should also update the other applications which make up Anbox. Keeping up to date ensures you have the latest fixes and security patches for smooth operation of your cluster. -For details about the Anbox Cloud release roadmap, see [Release roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359). +For details about the Anbox Cloud release roadmap, see {ref}`ref-roadmap`. ## Data backup @@ -70,13 +73,13 @@ Anbox Cloud is optimised to use only as much energy as is necessary for an opera * What trade-offs does your requirement allow to improve energy efficiency? For example, is there a way to use a lower streaming resolution? Lowering the resolution will impact the streaming experience but where possible, it could be a trade-off between being energy efficient and the quality of the stream. This needs to be decided based on how you use Anbox Cloud. * Does your deployment use GPU encoding or CPU encoding? * What is the bandwidth consumption of your deployment and what are the factors that could make it more efficient? -* Are you using the [appropriate platform](https://discourse.ubuntu.com/t/37322#supported-platforms-3) for your use case? For example, for automation use cases, `null` requires much less CPU usage than `webrtc` with GPU or CPU rendering. +* Are you using the appropriate platform for your use case? For example, for automation use cases, `null` requires much less CPU usage than `webrtc` with GPU or CPU rendering. See {ref}`exp-platforms` for more information. ## Monitoring and metrics Although Anbox Cloud does not offer its own observability solution, Anbox Cloud gathers various performance metrics that you can access through API endpoints to create a monitoring solution. -To create a customised monitoring solution, see [Prometheus metrics](https://discourse.ubuntu.com/t/prometheus-metrics/19521) for a detailed understanding of available metrics to assess your monitoring needs for the production deployment. See [Performance](https://discourse.ubuntu.com/t/29416) to learn about the factors that could influence the performance of your deployment. +To create a customised monitoring solution, see {ref}`ref-prometheus-metrics` for a detailed understanding of available metrics to assess your monitoring needs for the production deployment. See {ref}`exp-performance` to learn about the factors that could influence the performance of your deployment. ## Licensing and Support @@ -84,6 +87,6 @@ You need the Ubuntu Pro subscription to use Anbox Cloud. Depending on the type o ## Upgrade -When you consider a production deployment, it is important to assess your upgrade roadmap. For more information about upgrading Anbox Cloud and the prerequisites required for the upgrade process, see [How to upgrade Anbox Cloud](https://discourse.ubuntu.com/t/how-to-upgrade-anbox-cloud/17750). +When you consider a production deployment, it is important to assess your upgrade roadmap. For more information about upgrading Anbox Cloud and the prerequisites required for the upgrade process, see {ref}`howto-upgrade-anbox-cloud`. -You can also choose to subscribe to the [announcements about Anbox Cloud releases](https://discourse.ubuntu.com/c/anbox-cloud/announcements/55) on discourse. For insights into the Anbox Cloud release roadmap, see [Release roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359). \ No newline at end of file +You can also choose to subscribe to the [announcements about Anbox Cloud releases](https://discourse.ubuntu.com/c/anbox-cloud/announcements/55) on discourse. For insights into the Anbox Cloud release roadmap, see {ref}`ref-roadmap`. diff --git a/explanation/rendering-architecture.md b/explanation/rendering-architecture.md index 70fed7e4..43604b66 100644 --- a/explanation/rendering-architecture.md +++ b/explanation/rendering-architecture.md @@ -1,10 +1,13 @@ +(exp-rendering-architecture)= +# Rendering architecture + The rendering pipeline of Anbox Cloud can vary depending on the GPU used. This guide explains in detail, the rendering architecture of Anbox Cloud while discussing the different rendering pipeline models. ## Overview For AMD, Intel and NVIDIA GPUs, an OpenGL ES or EGL driver is layered on top of the [Vulkan API](https://www.vulkan.org/). Since Vulkan API provides better GPU management at a lower level than [OpenGL ES](https://www.khronos.org/opengles/) or [EGL](https://www.khronos.org/egl), this approach is beneficial and preferred by many users. -To have a better understanding of the rendering architecture of Anbox Cloud, it is important to understand what the Android framework offers in terms of rendering. In Android, applications interact with the SurfaceFlinger which is the system compositor that is responsible for composing a frame together from all the outputs rendered by different applications. The frame is then submitted to the hardware composer which renders the frames on a screen. For more information on Android graphics components and how they work, see https://source.android.com/docs/core/graphics. +To have a better understanding of the rendering architecture of Anbox Cloud, it is important to understand what the Android framework offers in terms of rendering. In Android, applications interact with the SurfaceFlinger which is the system compositor that is responsible for composing a frame together from all the outputs rendered by different applications. The frame is then submitted to the hardware composer which renders the frames on a screen. For more information on Android graphics components and how they work, see [Android documentation on Graphics](https://source.android.com/docs/core/graphics). ## Rendering pipeline @@ -32,9 +35,8 @@ Starting 1.22.0, Anbox Cloud uses VirGL as the default renderer for NVIDIA GPUs. For AMD and Intel GPUs, Anbox Cloud uses Vulkan as API in the Android space and we use [ANGLE](https://chromium.googlesource.com/angle/angle) on top of Vulkan to circumvent OpenGL ES and EGL. Since the Mesa driver (vendor GPU driver) is available directly in the Android space, we do not have the overhead of the remote procedure call implementation as in the pipeline for NVIDIA. -## Related information +## Related topics -* [Supported rendering resources](https://discourse.ubuntu.com/t/37322) +* {ref}`ref-rendering-resources` * [SurfaceFlinger](https://source.android.com/docs/core/graphics/surfaceflinger-windowmanager) * [Wayland](https://wayland.freedesktop.org/) - diff --git a/explanation/resources.md b/explanation/resources.md index df9787ec..71b9f609 100644 --- a/explanation/resources.md +++ b/explanation/resources.md @@ -1,3 +1,6 @@ +(exp-resources-presets)= +# Resources and resource presets + Resource presets denote the resources available to an instance. Anbox Cloud uses some default resource presets if there are no custom resource requirements specified. For a container instance, the default resource preset is: @@ -23,6 +26,6 @@ If your application requires different resources than the default, specify the r In addition to the `cpus`, `memory` and the `disk-size` requirements, if your application requires a custom number of GPU slots, change the `gpu-slots` value for the `resources` attribute in the application manifest. -## Related information +## Related topics -* [Application manifest](https://discourse.ubuntu.com/t/application-manifest/24197) +* {ref}`ref-application-manifest` diff --git a/explanation/security.md b/explanation/security.md index 714215db..41367a9a 100644 --- a/explanation/security.md +++ b/explanation/security.md @@ -1,14 +1,17 @@ +(exp-security)= +# Security + Anbox Cloud is secure by design, which means that its architecture, its components and all communication between components are designed to be fundamentally secure. Anbox Cloud uses the secure [LXD](https://ubuntu.com/lxd) for container and virtual machine management. To ensure security and isolation of each Android system, Anbox Cloud runs a single Android system per LXD instance. Consider the following simple yet impactful measures to ensure that you run a secure Anbox Cloud deployment: -- Always run the latest and supported version of Anbox Cloud. See [roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359). -- Do not set the `application.auto_update`, `instance.security_updates`, `container.security_updates` to `false`. See [AMS configuration](https://discourse.ubuntu.com/t/ams-configuration/20872). +- Always run the latest and supported version of Anbox Cloud. See {ref}`ref-roadmap`. +- Do not set the `application.auto_update`, `instance.security_updates`, `container.security_updates` to `false`. See {ref}`ref-ams-configuration`. - Monitor resources used by instances regularly. - Do not disable TLS pinning when you are not using a load balancer. -- Use the [Anbox Cloud dashboard](https://discourse.ubuntu.com/t/anbox-cloud-web-dashboard/41847) as your default stream client. If you want to use a custom client, ensure you have [set it up securely](https://discourse.ubuntu.com/t/set-up-a-stream-client/37328). +- Use the {ref}`exp-web-dashboard` as your default stream client. If you want to use a custom client, ensure you have set it up securely as described in the {ref}`tut-set-up-stream-client` tutorial. To report a security issue, contact the [Ubuntu security team](https://wiki.ubuntu.com/SecurityTeam/FAQ#Contact). @@ -43,19 +46,21 @@ Using virtual machines to host Android containers provides better workload isola ### Unprivileged instances -[note type="information" status="Note"]This section is particularly applicable for container based instances because a virtual machine is unprivileged by nature.[/note] +```{note} +This section is particularly applicable for container based instances because a virtual machine is unprivileged by nature. +``` Many instance managers use privileged instances, which means that the instances have root privileges on the host system, including access to all devices. This is a security risk, because attackers could gain control over the host system. Anbox Cloud uses unprivileged LXD instances only, which fully isolates the instances and ensures that they cannot gain root privileges. In addition, the Android container that runs inside the LXD instance also runs as an unprivileged instance. This method isolates the Android container twice, with the result that if the encapsulation of either the LXD instance or the Android container should fail, the system would still be protected. -[note type="caution" status="Warning"] +```{caution} While instances are fully isolated, all instances currently use the same GPU resources. As a result, any instance that is launched with GPU support could take all GPU resources in a DDoS-like attack, which would prevent other instances from starting. Monitoring how the GPU resources are used for different applications and ensuring that you are running trusted workloads can provide insulation against DDoS-like attacks. -See [GPU slots](https://discourse.ubuntu.com/t/about-capacity-planning/28717#gpu-slots-2) for more information. -[/note] +See {ref}`sec-gpu-slots` for more information. +``` ### Secure communication with the Juju controller @@ -67,17 +72,17 @@ See [Security with Juju](https://juju.is/docs/juju/juju-security) for more infor ### Security updates -Anbox Cloud provides images that are frequently updated with the latest security patches. When an image is updated, all Anbox Cloud applications that use the image are automatically updated as well (unless disabled with [`application.auto_update`](https://discourse.ubuntu.com/t/ams-configuration/20872)). +Anbox Cloud provides images that are frequently updated with the latest security patches. When an image is updated, all Anbox Cloud applications that use the image are automatically updated as well (unless disabled with `application.auto_update`,See {ref}`ref-ams-configuration`). In addition, to ensure that the latest Ubuntu security patches are applied outside of image updates as well, Anbox Cloud checks for and installs available security updates every time an application is bootstrapped. So when you create an application, its underlying image is updated with the latest Ubuntu security patches. You can also create a new application version without other changes to bootstrap the application again, and thus install the latest security patches. -It is possible to turn off this update mechanism by setting [`container.security_updates`](https://discourse.ubuntu.com/t/ams-configuration/20872) to `false`, but it is not recommended to do so. +It is possible to turn off this update mechanism by setting `container.security_updates` to `false`, but it is not recommended to do so. See {ref}`ref-ams-configuration`. For security reasons, always keep your systems up-to-date at all times. To ensure this, snaps update automatically, and the snap daemon is by default configured to check for updates four times a day. ## Android security -The images that Anbox Cloud provides are based on different Android versions. They are updated with security patches monthly, based on the upstream security tags. You can find detailed information on the security patches that have been included (or considered to be included but found unrelated) in the [Android Security Bulletins](https://source.android.com/docs/security/bulletin). The relevant security bulletin for each Anbox Cloud release is linked in the [Release notes](https://discourse.ubuntu.com/t/release-notes/17842). +The images that Anbox Cloud provides are based on different Android versions. They are updated with security patches monthly, based on the upstream security tags. You can find detailed information on the security patches that have been included (or considered to be included but found unrelated) in the [Android Security Bulletins](https://source.android.com/docs/security/bulletin). The relevant security bulletin for each Anbox Cloud release is linked in the {ref}`ref-release-notes`. See [Android Security Features](https://source.android.com/docs/security/features) in the Android documentation for an overview of security-related features that Android provides. Anbox Cloud supports some of these features, but not all of them. Some of the features rely on hardware that is not available in a virtual system, and others interfere with the Ubuntu security features. diff --git a/explanation/web-dashboard.md b/explanation/web-dashboard.md index 3c368eee..5c60ab99 100644 --- a/explanation/web-dashboard.md +++ b/explanation/web-dashboard.md @@ -1,3 +1,6 @@ +(exp-web-dashboard)= +# Anbox Cloud dashboard + The Anbox Cloud dashboard offers a web interface to create, manage and stream applications. The dashboard is especially helpful for developers new to Anbox Cloud and helps them by offering a simpler and intuitive management interface. The dashboard comes pre-installed when you deploy the full version of Anbox Cloud (along with the streaming stack) or the Anbox Cloud appliance. It operates from behind a reverse proxy for performance and security reasons. The dashboard relies on OAuth for user authentication. The only OAuth provider supported right now is [Ubuntu One](https://login.ubuntu.com/). @@ -11,13 +14,13 @@ The dashboard allows multiple views and management of various objects such as ap * Instances view - Allows a detailed view of instances and the applications or images that they are created from, along with management options for the instances. * Nodes view - Allows a list view of LXD nodes and their configuration details. -Apart from these views, the dashboard also allows you to work with the [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/anbox-application-registry-aar/17761) and the [Anbox Management Service (AMS)](https://discourse.ubuntu.com/t/anbox-management-service-ams/24321). +Apart from these views, the dashboard also allows you to work with the {ref}`exp-aar` and the {ref}`exp-ams`. * Registry view - Allows a list view of applications uploaded to the registry. -* Configuration view - Allows you to edit the [AMS configuration](https://discourse.ubuntu.com/t/ams-configuration/20872) attributes from the dashboard. +* Configuration view - Allows you to edit the {ref}`ref-ams-configuration` attributes from the dashboard. -## Related information +## Related topics -* [How to use the web dashboard](https://discourse.ubuntu.com/t/20871) -* [Install Anbox Cloud](https://discourse.ubuntu.com/t/17744) -* [Install Anbox Cloud Appliance](https://discourse.ubuntu.com/t/22681) +* {ref}`tut-installing-appliance` +* {ref}`howto-use-web-dashboard` +* {ref}`howto-deploy-anbox-juju` diff --git a/howto/aar/configure.md b/howto/aar/configure.md index cae421ec..22a77277 100644 --- a/howto/aar/configure.md +++ b/howto/aar/configure.md @@ -1,10 +1,13 @@ -The [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/application-registry/17761) uses a certificate-based authentication system that uses TLS server and client certificates to establish a trusted connection between the AAR and AMS. +(howto-configure-aar)= +# How to configure an AAR + +The Anbox Application Registry (AAR) uses a certificate-based authentication system that uses TLS server and client certificates to establish a trusted connection between the AAR and AMS. AAR and AMS must exchange certificates to set up a trust relation. The recommended way to do this is with Juju. If you are using the Anbox Cloud Appliance, however, you must register the clients manually. ## Register an instance using Juju (recommended) -If you are running a full Anbox Cloud deployment, use [Juju relations](https://jaas.ai/docs/relations) to register an instance with the AAR. +If you are running a full Anbox Cloud deployment, use Juju relations to register an instance with the AAR. To register an instance as a client, use the following command: @@ -14,11 +17,13 @@ To register an instance as a publisher, use the following command: juju add-relation aar:publisher ams:registry-publisher -[note type="information" status="Tip"]Run `amc config show` to check that the AAR configuration items were changed.[/note] +```{tip} +Run `amc config show` to check that the AAR configuration items were changed. +``` ### Register units deployed in another model -For `ams` units deployed in another model, you can make use of [Juju cross model relations](https://juju.is/docs/cross-model-relations). +For `ams` units deployed in another model, you can make use of Juju cross model relations. Enter the following commands: @@ -108,20 +113,27 @@ Use "aar trust [command] --help" for more information about a command. Every AMS instance has a registry-specific client certificate that is stored at `/var/snap/ams/common/registry/client.crt`. To manually register an AMS client, you'll need to copy this certificate to the machine hosting AAR and use the CLI to trust it. -To add an AMS client as a trusted [publisher](https://discourse.ubuntu.com/t/anbox-application-registry-aar/17761#how-aar-works-1), use the following command: +To add an AMS client as a trusted publisher, use the following command: sudo aar trust add client.crt --publisher -To add an AMS client as a trusted [client](https://discourse.ubuntu.com/t/anbox-application-registry-aar/17761#how-aar-works-1), use the following command: +To add an AMS client as a trusted client, use the following command: sudo aar trust add client.crt -[note type="information" status="Note"] +```{note} Due to Snap strict confinement and the AAR `sudo` requirement, the command requires the certificates to be located in the root user home directory `/root`. To work around this requirement, use the following command: `cat client.crt | sudo aar trust add [--publisher]` -[/note] +``` Finally, reboot the AAR: snap restart aar + +## Related topics + +* {ref}`exp-aar` +* {ref}`howto-revoke-aar` +* [Juju relations](https://jaas.ai/docs/relations) +* [Juju cross model relations](https://juju.is/docs/cross-model-relations) \ No newline at end of file diff --git a/howto/aar/deploy.md b/howto/aar/deploy.md index ffcd588d..5093f2b3 100644 --- a/howto/aar/deploy.md +++ b/howto/aar/deploy.md @@ -1,4 +1,7 @@ -An [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/application-registry/17761) should be deployed on a single unit. After deploying, continue to [configure it](https://discourse.ubuntu.com/t/configure-an-aar/24319) and connect it with all AMS units that you want to synchronise. +(howto-deploy-aar)= +# How to deploy an AAR + +An Anbox Application Registry (AAR) should be deployed on a single unit. After deploying, you can continue to configure and connect it with all AMS units that you want to synchronise. Use the following commands to deploy an AAR: @@ -13,13 +16,13 @@ When using the S3 storage backend, image downloads will be redirected to S3 inst ### Create and configure an S3 bucket -To use the AWS S3 storage backend, you must create a dedicated S3 bucket for the AAR first. See the AWS documentation [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) for instructions on how to do this. +To use the AWS S3 storage backend, you must create a dedicated S3 bucket for the AAR first. See the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) for instructions on how to do this. -If you don’t plan to use the [CloudFront CDN](#aws-cloudfront-cdn-support-3), you should use a region close to your Anbox Cloud deployment to keep download times low. +If you don’t plan to use the {ref}`CloudFront CDN `, you should use a region close to your Anbox Cloud deployment to keep download times low. ### Configure bucket access for AAR -To allow the AAR to access the S3 bucket, create an [IAM Policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html): +To allow the AAR to access the S3 bucket, create an IAM Policy. See [AWS documentation on IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) for more information: ```json { @@ -55,9 +58,9 @@ Replace `aar0` in the policy with the name of your bucket. There are two ways to configure the bucket access for AAR using the policy created earlier: -1. Create an IAM user and an access key for this user, which the AAR will use. See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for more details on this. Assign the policy created earlier to this user. +1. Create an IAM user and an access key for this user, which the AAR will use. See the [AWS documentation on managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for more information. Assign the policy created earlier to this user. -2. Create an instance profile using the IAM policy created earlier and attach the instance profile to the instance where AAR is deployed. For more information, see the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) for more details on this. +2. Create an instance profile using the IAM policy created earlier and attach the instance profile to the instance where AAR is deployed. See the [AWS documentation on using instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) for more information. ### Configure AAR @@ -81,9 +84,10 @@ Finally, update the AAR configuration via the charm configuration: juju config aar -f config.yaml +(sec-aws-cloudfront-cdn)= ### AWS CloudFront CDN support -The distribution of the images can be highly improved by adding support for the AWS CloudFront CDN, which brings the images closer to your Anbox Cloud deployments in a more world wide context. The [AWS documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html) describes all necessary setup steps. +The distribution of the images can be highly improved by adding support for the AWS CloudFront CDN, which brings the images closer to your Anbox Cloud deployments in a more world wide context. See the [Getting Started Guide on Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html) for more information. Once you have set up a CloudFront distribution for your S3 bucket, you only need the base URL, public key and key pair ID to configure the AAR to use CloudFront to serve image downloads. @@ -114,3 +118,9 @@ aar: Then update the AAR configuration via the charm configuration: juju config aar -f config.yaml + +## Related topics + +* {ref}`exp-aar` +* {ref}`howto-configure-aar` +* {ref}`howto-revoke-aar` \ No newline at end of file diff --git a/howto/aar/landing.md b/howto/aar/landing.md index 04bd03d0..9a0ad274 100644 --- a/howto/aar/landing.md +++ b/howto/aar/landing.md @@ -1,2 +1,13 @@ -The guides in this section describe how to manage the Anbox Application Registry (AAR). -See [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/anbox-application-registry-aar/17761) for an overview of AAR and how it works. +(howto-aar)= +# How to manage an AAR + +The following guides in this section describe how to manage the Anbox Application Registry (AAR). + +```{toctree} +:titlesonly: + +Configure AAR +Deploy AAR +Revoke an AAR client +``` +See {ref}`exp-aar` for an overview of AAR and how it works. \ No newline at end of file diff --git a/howto/aar/revoke.md b/howto/aar/revoke.md index 3c1bcea6..76baef2d 100644 --- a/howto/aar/revoke.md +++ b/howto/aar/revoke.md @@ -1,4 +1,8 @@ -If a client gets compromised, it's important to block its access to the [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/application-registry/17761) by revoking its certificate. +(howto-revoke-aar)= + +# How to revoke an AAR client + +If a client gets compromised, it's important to block its access to the Anbox Application Registry (AAR) by revoking its certificate. Revoked clients are blocked from accessing the AAR. You'll need to create a new certificate and add it manually for the client to be trusted again. @@ -6,4 +10,12 @@ Use the following command to revoke a certificate: aar trust revoke -[note type="caution" status="Warning"]This operation is irreversible. You cannot reverse a revocation or add the certificate again.[/note] +```{caution} +This operation is irreversible. You cannot reverse a revocation or add the certificate again. +``` + +## Related topics + +* {ref}`exp-aar` +* {ref}`howto-configure-aar` +* {ref}`howto-deploy-aar` diff --git a/howto/addons/backup-and-restore.md b/howto/addons/backup-and-restore.md index ebe70ef0..b36f6d93 100644 --- a/howto/addons/backup-and-restore.md +++ b/howto/addons/backup-and-restore.md @@ -1,3 +1,5 @@ +(howto-backup-restore-example)= +# Example: Back up data When an instance is stopped, all the data and logs produced during the runtime are lost. To avoid this, you can use hooks to back up and restore any type of data you want. ## Back up data diff --git a/howto/addons/create.md b/howto/addons/create.md index d22ece11..decaf31c 100644 --- a/howto/addons/create.md +++ b/howto/addons/create.md @@ -1,9 +1,12 @@ +(howto-create-addons)= +# How to create an addon + To create or update an addon, you need a specific file structure for the directory containing your addon files. In the directory where you created your addon files, also create the following: -- A file named `manifest.yaml`. See [Addon manifest](https://discourse.ubuntu.com/t/25293) to learn about valid keys in an addon manifest file. +- A file named `manifest.yaml`. See {ref}`ref-addon-manifest` to learn about valid keys in an addon manifest file. - A directory named `hooks`. This directory must contain at least one executable file with a valid hook name. -Other files in the addon directory are bundled with the addon. They can be accessed in a hook by using the `$ADDON_DIR` [environment variable](https://discourse.ubuntu.com/t/hooks/28555#environment-variables-1). +Other files in the addon directory are bundled with the addon. They can be accessed in a hook by using the `$ADDON_DIR` environment variable. See {ref}`sec-env-variables` for more information. For example: diff --git a/howto/addons/customise-android.md b/howto/addons/customise-android.md index dd093df4..d3135c89 100644 --- a/howto/addons/customise-android.md +++ b/howto/addons/customise-android.md @@ -1,3 +1,6 @@ +(howto-customise-android-example)= +# Example: Customise Android + To do any customisation to the Android system that runs your application, use the `anbox-shell` tool within a hook. This tool is useful to interact with the Android system directly. In this example, we create a hook that configures the Android system to use an HTTP proxy: diff --git a/howto/addons/emulate-platforms.md b/howto/addons/emulate-platforms.md index 074f5bfe..e9e114fa 100644 --- a/howto/addons/emulate-platforms.md +++ b/howto/addons/emulate-platforms.md @@ -1,3 +1,6 @@ +(howto-emulate-platforms-example)= +# Example: Emulate platforms + To provide support for platforms that are not natively supported by your application (for example, you want to run an x86_64 application on Arm), use a hook. Create a hook that installs the software for binary translation and add the top-level key `provides` to your addon manifest. List the architectures that the addon supports, in the value for the `provides` key. diff --git a/howto/addons/enable-globally.md b/howto/addons/enable-globally.md index 01d23d52..52fbd190 100644 --- a/howto/addons/enable-globally.md +++ b/howto/addons/enable-globally.md @@ -1,4 +1,7 @@ -To enable an addon for an application, you must add it to the [application manifest](https://discourse.ubuntu.com/t/application-manifest/24197). +(howto-enable-addons-globally)= +# How to enable an addon globally + +To enable an addon for an application, you must add it to the application manifest. However, if you want to use the same addon or addons for all your applications, you can enable them globally. To do so, run the following command after creating your addons: @@ -10,4 +13,10 @@ This command adds the `foo` and `bar` addons to all your new and existing applic If you define both global addons and application-specific addons, applications will use both. -[note type="caution" status="Warning"]Addons can delay the start of your applications. Therefore, keep them light.[/note] +```{caution} +Addons can delay the start of your applications. Therefore, keep them light. +``` + +## Related topics + +* {ref}`ref-application-manifest` diff --git a/howto/addons/install-tools.md b/howto/addons/install-tools.md index dfcc7cfb..d086b89d 100644 --- a/howto/addons/install-tools.md +++ b/howto/addons/install-tools.md @@ -1,3 +1,6 @@ +(howto-install-tools-example)= +# Example: Install tools + Application images are designed to be as lightweight as possible, and as such, common tools you might expect to see in a regular cloud image might not be available. You can use hooks to install packages that you require for your application. In this example, we'll install `curl` and `python3`. diff --git a/howto/addons/landing.md b/howto/addons/landing.md index 74dc5fa7..6a49d9d3 100644 --- a/howto/addons/landing.md +++ b/howto/addons/landing.md @@ -1,13 +1,30 @@ -In Anbox Cloud, addons can be used to customise the images used for the [instances](https://discourse.ubuntu.com/t/26204#instance). See [Addons](https://discourse.ubuntu.com/t/38727) and [Addon manifest](https://discourse.ubuntu.com/t/25293) to learn about addons in detail. +(howto-addons)= +# How to manage addons -If this is your first time creating an addon, follow the [Create an addon](https://discourse.ubuntu.com/t/creating-an-addon/25284) tutorial to learn how to write a simple addon. +In Anbox Cloud, addons can be used to customise images that are used for instances. See {ref}`exp-addons` and {ref}`ref-addon-manifest` to learn about addons in detail. + +If this is your first time creating an addon, follow the {ref}`tut-create-addon` tutorial to learn how to write a simple addon. You can use addons to, for example: -- Enable SSH access for automation tools (see [Create an addon](https://discourse.ubuntu.com/t/creating-an-addon/25284)) -- Set up user-specific data when starting an application (see [How to restore data](https://discourse.ubuntu.com/t/example-back-up-data/25289#restore-data-2)) -- Install additional tools in the instance (see [Example: Install tools](https://discourse.ubuntu.com/t/example-install-tools/25288)) -- Back up data when the instance is stopping (see [Example: Back up data](https://discourse.ubuntu.com/t/example-back-up-data/25289)) -- Configure the Android system before running the application (see [Example: Customise Android](https://discourse.ubuntu.com/t/example-customise-android/25290)) -- Provide support for other platforms (see [Example: Emulate platforms](https://discourse.ubuntu.com/t/example-emulate-platforms/25291)) - -If you have used addons before Anbox Cloud 1.12, see the [migration guide](https://discourse.ubuntu.com/t/migrate-from-previous-addon-versions/25287) to update your addons to use the new hooks. +- Enable SSH access for automation tools (see {ref}`tut-create-addon`) +- Set up user-specific data when starting an application (see {ref}`howto-backup-restore-example`) +- Install additional tools in the instance (see {ref}`howto-install-tools-example`) +- Back up data when the instance is stopping (see {ref}`howto-backup-restore-example`) +- Configure the Android system before running the application (see {ref}`howto-customise-android-example`) +- Provide support for other platforms (see {ref}`howto-emulate-platforms-example`) + +If you have used addons before Anbox Cloud 1.12, see {ref}`howto-migrate-addons` to update your addons to use the new hooks. + +```{toctree} +:hidden: + + +Create an addon +Enable an addon globally +Migrate addons to new hooks +Update addons +Example: Customise Android +Example: Emulate platforms +Example: Backup and restore data +Example: Install tools +``` diff --git a/howto/addons/migrate.md b/howto/addons/migrate.md index 14d4e046..1fdaf8ce 100644 --- a/howto/addons/migrate.md +++ b/howto/addons/migrate.md @@ -1,3 +1,6 @@ +(howto-migrate-addons)= +# How to migrate from previous versions + Starting with Anbox Cloud 1.12, use the following new hooks instead of the deprecated ones: * Use `pre-start` instead of `install` @@ -16,4 +19,6 @@ fi # Rest of the code for your addon ``` -[note type="caution" type="Warning"]Copying your existing addons without modifications might have unintended side effects, because your hooks will run for every instance.[/note] +```{caution} +Copying your existing addons without modifications might have unintended side effects, because your hooks will run for every instance. +``` diff --git a/howto/addons/update.md b/howto/addons/update.md index f9da8c37..f927faae 100644 --- a/howto/addons/update.md +++ b/howto/addons/update.md @@ -1,8 +1,13 @@ +(howto-update-addons)= +# How to update addons + You can update an existing addon with a new version by using the following command: ```bash amc addon update foo ./foo-addon ``` -[note type="information" status="Note"]Due to Snap strict confinement, the addon must be located in your home directory.[/note] +```{note} +Due to Snap strict confinement, the addon must be located in your home directory. +``` AMS will update the addon and create a new version for all applications that use this addon in the background. If the addon you are updating is used by many applications, you might experience increased load on your cluster while AMS updates many applications simultaneously. diff --git a/howto/anbox/develop-addon.md b/howto/anbox-runtime/develop-addon.md similarity index 89% rename from howto/anbox/develop-addon.md rename to howto/anbox-runtime/develop-addon.md index 25ab8c2f..3f05303d 100644 --- a/howto/anbox/develop-addon.md +++ b/howto/anbox-runtime/develop-addon.md @@ -1,6 +1,9 @@ +(howto-develop-addons-devmode)= +# How to develop addons in `--devmode` + Developing and testing addons using the Anbox Management Service (AMS) may be time-consuming. Instead, an instance with `--devmode` enabled can provide a safe environment to develop and test addons and their hooks without having to upload the addon to the AMS. -This guide explains how to use an instance in development mode to develop and test an addon using Anbox runtime. See [development mode](https://discourse.ubuntu.com/t/17763#dev-mode) to learn more about development mode enabled instances. +This guide explains how to use an instance in development mode to develop and test an addon using Anbox runtime. See {ref}`sec-dev-mode` to learn more about development mode enabled instances. ## Launch an instance in development mode @@ -24,7 +27,7 @@ Alternatively, you can use `amc exec ` to directl Use the instance as a remote environment to develop your addon. To make your addon source available within the instance, either copy the addon manifest and hooks using the [`lxc file push`](https://documentation.ubuntu.com/lxd/en/latest/howto/instances_access_files/#push-files-from-the-local-machine-to-the-instance) command or clone a git repository using SSH. -You can test your addon hooks by running it inside the instance shell. For example, `ADDON_DIR=$PWD ./hooks/install` can help test if the install hook of the addon works. See [environment variables](https://discourse.ubuntu.com/t/28555#environment-variables-1) for a list of available variables. +You can test your addon hooks by running it inside the instance shell. For example, `ADDON_DIR=$PWD ./hooks/install` can help test if the install hook of the addon works. See {ref}`sec-env-variables` for a list of available variables. To troubleshoot issues within the instance, try either of the following options: * Run `amc logs ` on the host to see the Anbox runtime logs. diff --git a/howto/anbox/develop-platform.md b/howto/anbox-runtime/develop-platform.md similarity index 70% rename from howto/anbox/develop-platform.md rename to howto/anbox-runtime/develop-platform.md index d4c494a7..f1b14359 100644 --- a/howto/anbox/develop-platform.md +++ b/howto/anbox-runtime/develop-platform.md @@ -1,6 +1,9 @@ -Anbox Cloud provides a platform SDK that allows the development of custom platform plugins for the Anbox runtime, for use cases where the [default platforms](https://discourse.ubuntu.com/t/18733) don't fit. For example, a custom platform can be used to integrate a custom streaming protocol with the Anbox runtime. +(howto-develop-platform-plugin)= +# How to develop a platform plugin -This guide assumes that all steps are run on an Ubuntu 22.04 machine that hosts the [Anbox Cloud Appliance](https://discourse.ubuntu.com/t/install-appliance/22681). +Anbox Cloud provides a platform SDK that allows the development of custom platform plugins for the Anbox runtime, for use cases where the default platforms (see {ref}`exp-platforms`) don't fit. For example, a custom platform can be used to integrate a custom streaming protocol with the Anbox runtime. + +This guide assumes that all steps are run on an Ubuntu 22.04 machine that hosts the Anbox Cloud Appliance. See {ref}`tut-installing-appliance`. ## Preparation @@ -8,11 +11,11 @@ A platform module must be built on the same version of Ubuntu as the Anbox runti However, if you're running the Anbox Cloud Appliance on a machine with a different Ubuntu version, you can build the platform on a separate system (for example, in a LXD or docker instance or on another machine). -To get started, you must first install the [Anbox Platform SDK](https://github.com/canonical/anbox-platform-sdk). To do so, follow the [installation instructions](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-platform-sdk-1). +To get started, you must first install the [Anbox Platform SDK](https://github.com/canonical/anbox-platform-sdk). See {ref}`ref-sdks` for more information. ## Build the example platform -The [Anbox Platform SDK](https://github.com/canonical/anbox-platform-sdk) comes with various examples that demonstrate different features. The following steps use the `minimal` example. Alternatively, choose the `nvidia` example if you're working with NVIDIA GPUs and want to see graphical output. +The Anbox Platform SDK comes with various examples that demonstrate different features. The following steps use the `minimal` example. Alternatively, choose the `nvidia` example if you're working with NVIDIA GPUs and want to see graphical output. To build the `minimal` platform example, run the following commands: @@ -29,23 +32,27 @@ The build process creates a `platform_minimal.so` module in the `build` director ## Install the example platform -[AMS](https://discourse.ubuntu.com/t/about-ams/24321) allows launching instances in a special [development mode](https://discourse.ubuntu.com/t/17763#dev-mode), which is helpful when developing, for example, addons or platforms. In development mode, the Anbox runtime does not terminate the instance when it detects failures or other problems. +The Anbox Management Service (AMS) allows launching instances in a special development mode, which is helpful when developing addons or platforms. In development mode, the Anbox runtime does not terminate the instance when it detects failures or other problems. + +We will be using this development mode to install the platform. See {ref}`sec-dev-mode` for more information. To try out the `minimal` platform, complete the following steps: -1. Start a [raw instance](https://discourse.ubuntu.com/t/17763#application-vs-raw) with development mode turned on: +1. Start a raw instance with development mode turned on: - amc launch --raw --devmode --instance-type=a4.3 + amc launch --raw --devmode --cpus 4 --memory 3GB - If you chose the `nvidia` example, you must select an [instance type](https://discourse.ubuntu.com/t/application-manifest/24197#instance-type-1) that supports GPUs: + If you chose the `nvidia` example, you must select an instance type that supports GPUs (See {ref}`sec-application-manifest-instance-type` if you need more information on the different instance types): - amc launch --raw --devmode --instance-type=g4.3 + amc launch --raw --devmode --cpus 4 --memory 3GB --gpu-slots 1 - [note type="information" status="Note"]Use the `--vm` option to launch a VM instance.[/note] + ```{note} + Use the `--vm` option to launch a VM instance. + ``` The command prints out the ID of the instance. Note down this ID; you will need it in the next step. - The start of the raw instance takes some time, because it runs through the full [bootstrap process](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2) before the instance is ready to be used. + The start of the raw instance takes some time, because it runs through the full bootstrap process before the instance is ready to be used. See {ref}`sec-application-bootstrap` for more information on the bootstrap process. 1. When the instance is fully up and running, copy the `platform_minimal.so` module to it: @@ -89,7 +96,7 @@ When you want to stop Anbox, you can use `CTRL`+`C` to send it the signal to ter ## Package the platform -To ship the platform to actual instance via AMS, you must create an [addon](https://discourse.ubuntu.com/t/managing-addons/17759) package that installs the platform into the instance. +To ship the platform to actual instance via AMS, you must create an addon package that installs the platform into the instance. A very simple addon to install the created `minimal` platform looks as follows: @@ -117,3 +124,9 @@ When launching an instance, you must explicitly specify the platform that the An amc launch --raw --addon minimal --platform minimal Use the `--vm` option to launch a VM instance. + +## Related topics + +* {ref}`exp-addons` +* {ref}`exp-instances` +* {ref}`howto-create-addons` \ No newline at end of file diff --git a/howto/anbox-runtime/landing.md b/howto/anbox-runtime/landing.md new file mode 100644 index 00000000..43b72e95 --- /dev/null +++ b/howto/anbox-runtime/landing.md @@ -0,0 +1,13 @@ +(howto-anbox-runtime)= +# How to work with the Anbox runtime + +The guides in this section describe how to work with the Anbox runtime, which is responsible for running the Android container, providing access to any hardware and integrating with streaming protocols. + +The following guides are available: + +```{toctree} +:titlesonly: + +Develop addons in devmode +Develop a platform plugin +``` diff --git a/howto/manage/ams-access.md b/howto/anbox/ams-access.md similarity index 88% rename from howto/manage/ams-access.md rename to howto/anbox/ams-access.md index 81bdc76d..7fc49c52 100644 --- a/howto/manage/ams-access.md +++ b/howto/anbox/ams-access.md @@ -1,4 +1,7 @@ -By default, the Anbox Management Client (AMC) runs on the same machine as the [Anbox Management Service (AMS)](https://discourse.ubuntu.com/t/about-ams/24321) and connects to it through a UNIX socket. +(howto-access-ams-remote)= +# How to control AMS remotely + +By default, the Anbox Management Client (AMC) runs on the same machine as the Anbox Management Service (AMS) and connects to it through a UNIX socket. If you want to control AMS remotely, you can install the AMC on a separate machine and configure it to connect to AMS through a secure HTTP connection. @@ -12,7 +15,7 @@ To do so, use the following command: ## Install a trusted certificate -Controlling AMS remotely requires trusted security certificates. You can generate self-signed certificates or use certificates signed by a Certificate Authority. See [Security certificates for remote clients](https://discourse.ubuntu.com/t/anbox-management-service-ams/24321#security-certificates-for-remote-clients-2) for more information. +Controlling AMS remotely requires trusted security certificates. You can generate self-signed certificates or use certificates signed by a Certificate Authority. See {ref}`sec-security-cert-remote-clients` for more information. ### Self-signed certificates @@ -62,7 +65,9 @@ After setting up the security certificates, configure AMC to connect to the remo amc remote add https://:8444 -[note type="information" status="Tip"]If you haven't changed the port AMS is listening on, it's 8444 by default.[/note] +```{tip} +If you haven't changed the port AMS is listening on, it's 8444 by default. +``` The command connects to AMS and shows you the fingerprint of the server certificate. If it matches what you expect, acknowledge the fingerprint by typing "yes". @@ -71,3 +76,7 @@ Finally, switch to the new remote by running the following command: amc remote set-default All invocations of the `amc` command will from now on use the new remote. + +## Related topics + +* {ref}`exp-ams` diff --git a/howto/manage/benchmarks.md b/howto/anbox/benchmarks.md similarity index 90% rename from howto/manage/benchmarks.md rename to howto/anbox/benchmarks.md index 44b40a7e..04bff9bd 100644 --- a/howto/manage/benchmarks.md +++ b/howto/anbox/benchmarks.md @@ -1,8 +1,13 @@ +(howto-run-benchmarks)= +# How to run benchmarks + Anbox Cloud provides tools for benchmarking different aspects of your deployment. These tools enable you to put Anbox Cloud under load and use the results to evaluate the performance for a well-defined workload. -See [Performance benchmarks](https://discourse.ubuntu.com/t/performance-benchmarks/24709) for an overview of results that you can expect for selected hardware configurations. +See {ref}`ref-performance-benchmarks` for an overview of results that you can expect for selected hardware configurations. -[note type="information" status="Important"]Benchmarks provide useful information only if you run them with an application and workload that reflects your real-life scenario. For example, if you run the benchmark with an Android app that just sits idle and does not constantly refresh the screen by itself, you will get a low FPS number. This number does not reflect the real scenario though, because in reality, your users actually use the app and thus cause a higher workload.[/note] +```{important} +Benchmarks provide useful information only if you run them with an application and workload that reflects your real-life scenario. For example, if you run the benchmark with an Android app that just sits idle and does not constantly refresh the screen by itself, you will get a low FPS number. This number does not reflect the real scenario though, because in reality, your users actually use the app and thus cause a higher workload. +``` ## Run instance benchmarks @@ -14,7 +19,7 @@ Check the help output to see all available arguments and their purpose: amc benchmark -h -The benchmark command launches the specified number of instances on the Anbox [`null` platform](https://discourse.ubuntu.com/t/anbox-platforms/18733) with the following default display specification: +The benchmark command launches the specified number of instances on the Anbox `null` platform (see {ref}`exp-platforms`) with the following default display specification: | Display spec | Value | | ----------------------- | ----- | @@ -31,7 +36,9 @@ You can configure a different display specification through the `--userdata` par | `swrast` | Comma-separated values | ,,, | | `webrtc` | JSON-based | {
"display_width": ,
"display_height": ,
"display_density": ,
"fps": ,
"render_only": true
} | -[note type="information" status="Note"]If you're running a benchmark against the `webrtc` platform, make sure to specify `"render_only": true` to launch the instances in render-only mode. Otherwise, the instance creation will fail, because the `amc benchmark` command doesn't interact with the stream gateway for the benchmark execution.[/note] +```{note} +If you're running a benchmark against the `webrtc` platform, make sure to specify `"render_only": true` to launch the instances in render-only mode. Otherwise, the instance creation will fail, because the `amc benchmark` command doesn't interact with the stream gateway for the benchmark execution. +``` ### Example @@ -128,7 +135,7 @@ Check the help output to see all available arguments and their purpose: anbox-cloud-tests.benchmark -h -To run the benchmark, you must provide an authentication token for the Anbox Stream Gateway. Check [How to access the stream gateway](https://discourse.ubuntu.com/t/managing-stream-gateway-access/17784) if you haven't already created an authentication token. +To run the benchmark, you must provide an authentication token for the Anbox Stream Gateway. See {ref}`howto-access-stream-gateway` if you haven't already created an authentication token. If your Anbox Stream Gateway is behind a self-signed TLS certificate, you must specify the `--insecure-tls` option. diff --git a/howto/manage/images.md b/howto/anbox/images.md similarity index 92% rename from howto/manage/images.md rename to howto/anbox/images.md index beed6a72..7c46253c 100644 --- a/howto/manage/images.md +++ b/howto/anbox/images.md @@ -1,6 +1,9 @@ +(howto-manage-images)= +# How to manage Anbox Cloud images + An image is the base for an instance running in the Anbox Cloud. It contains all necessary components, like Anbox or the Android root file system. Each release of Anbox Cloud comes with an updated image. -See [Provided images](https://discourse.ubuntu.com/t/provided-images/24185) for information about which images Anbox Cloud provides. +See {ref}`ref-provided-images` for information about which images Anbox Cloud provides. ## Configure image server @@ -51,7 +54,9 @@ Images that are synchronised from the image server are marked as immutable. To d If you're not using `--force`, the command will fail. -[note type="information" status="Note"]Unless you have only one image left, you cannot delete an image that is marked as default. You must set a new default image first.[/note] +```{note} +Unless you have only one image left, you cannot delete an image that is marked as default. You must set a new default image first. +``` ### Delete an image version @@ -73,6 +78,6 @@ For instance, to fetch the arm64 Android 13 image of the 1.18.0 release: You can then use the `foobar` image as you would any other image. -[note type="information" status="Important"] +```{important} Image updates contain important security patches and optimisations. Use older images only when strictly necessary. -[/note] +``` diff --git a/howto/anbox/landing.md b/howto/anbox/landing.md index f3bdf220..559109d3 100644 --- a/howto/anbox/landing.md +++ b/howto/anbox/landing.md @@ -1,6 +1,16 @@ -The guides in this section describe how to work with the Anbox runtime, which is responsible for running the Android container, providing access to any hardware and integrating with streaming protocols. +(howto-manage-anbox)= +# How to manage Anbox Cloud -The following guides are available: +The following guides in this section help you to manage and work with your Anbox Cloud or Anbox Cloud Appliance installation. -* [How to develop a platform plugin](https://discourse.ubuntu.com/t/how-to-develop-a-platform-plugin/33099) -* [How to develop an addon](https://discourse.ubuntu.com/t/develop-and-test-addons-in-development-mode/36914) +```{toctree} +:titlesonly: + +Control AMS remotely +Manage images +Resize LXD storage +Run benchmarks +Set up TLS +``` + +You can also refer to {ref}`ref-appliance-commands` and {ref}`ref-amc-commands` for commands that you can use with the CLI. \ No newline at end of file diff --git a/howto/manage/resize-storage.md b/howto/anbox/resize-storage.md similarity index 87% rename from howto/manage/resize-storage.md rename to howto/anbox/resize-storage.md index 95e817d7..dbb439ad 100644 --- a/howto/manage/resize-storage.md +++ b/howto/anbox/resize-storage.md @@ -1,4 +1,7 @@ -Resizing the LXD storage pool that Anbox Cloud uses is not recommended. Before you deploy Anbox Cloud, you should analyse and plan the capacity you need, so that you can size the storage that you need correctly right from the start. See [About capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) for detailed information. +(howto-resize-lxd-storage)= +# How to resize LXD storage + +Resizing the LXD storage pool that Anbox Cloud uses is not recommended. Before you deploy Anbox Cloud, you should analyse and plan the capacity you need, so that you can size the storage that you need correctly right from the start. See {ref}`exp-capacity-planning` for detailed information. However, if you run into a situation where you need to grow the LXD storage pool, try the following workarounds depending on your setup. diff --git a/howto/manage/tls-for-appliance.md b/howto/anbox/tls-for-appliance.md similarity index 90% rename from howto/manage/tls-for-appliance.md rename to howto/anbox/tls-for-appliance.md index 36e6f0bc..f0da8055 100644 --- a/howto/manage/tls-for-appliance.md +++ b/howto/anbox/tls-for-appliance.md @@ -1,6 +1,11 @@ +(howto-set-up-tls)= +# Set up TLS for the Anbox Cloud Appliance + The Anbox Cloud Appliance uses a self-signed certificate to provide HTTPS services. If you want to serve the appliance over HTTPS using a valid SSL/TLS certificate, follow the steps in this document to generate and install a valid SSL/TLS certificate on the Anbox Cloud Appliance. -[note type="information" status="Note"]This document assumes you have the Anbox Cloud Appliance installed. If you haven't, follow the [instructions](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702) to do so.[/note] +```{note} +This document assumes you have the Anbox Cloud Appliance installed. If you haven't, follow the {ref}`tut-installing-appliance` tutorial to do so. +``` If you run the appliance on AWS, you can choose to use the AWS Certificate Manager. Otherwise, you must manage the certificate yourself manually. @@ -18,7 +23,9 @@ Configure the location for the appliance using the created DNS name: sudo snap set anbox-cloud-appliance experimental.location= -[note type="information" status="Note"]This option is experimental. It will be removed in a future release when a better replacement exists.[/note] +```{note} +This option is experimental. It will be removed in a future release when a better replacement exists. +``` ### 3. Generate an SSL certificate @@ -88,7 +95,9 @@ The `certbot` snap packages installed on your machine already set up a systemd t In this way, the SSL certificate auto-renewal is in place. -[note type="information" status="Note"]The appliance will face a short downtime during the renewal of the SSL certificate but will come back online once the process is completed.[/note] +```{note} +The appliance will face a short downtime during the renewal of the SSL certificate but will come back online once the process is completed. +``` ## Use the AWS Certificate Manager @@ -98,22 +107,23 @@ Before you start, make sure the following requirements are met: - You have a domain name for use with the Anbox Cloud Appliance registered, either through Amazon Route 53 (see [Register a new domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) in the Amazon Route 53 documentation) or through another domain provider. - [note type="information" status="Note"] + ```{note} The screenshots in the following instructions use an example domain name that is not owned or controlled by Canonical. Replace it with your own domain name when following the setup instructions. - [/note] -- The Anbox Cloud Appliance is [installed](https://discourse.ubuntu.com/t/how-to-install-the-appliance-on-aws/29703) and [initialised](https://discourse.ubuntu.com/t/install-the-anbox-cloud-appliance-on-a-dedicated-machine/22681#initialise-the-appliance-6). + ``` +- The Anbox Cloud Appliance is installed and initialised. See {ref}`howto-install-appliance-aws` and {ref}`sec-initialise-appliance` for instructions. Then complete the following steps. +(sec-configure-routing-info-name-servers)= ### 1. Configure routing information and name servers -[note type="information" status="Note"] +```{note} You can skip this step if you registered your domain name through Amazon Route 53. -[/note] +``` If you want to use a domain name that was not registered through Amazon Route 53, you must manually create a [public hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html) for it, and then make your domain use Amazon Route 53 as its DNS service. A public hosted zone contains routing information for the domain, and Amazon Route 53 uses it to determine to which machine it should route the traffic to your domain. -In the case of the Anbox Cloud Appliance, we want the traffic routed to the AWS load balancer (which we will set up in [step 3](#h-3-create-a-load-balancer-10). +In the case of the Anbox Cloud Appliance, we want the traffic routed to the AWS load balancer which we will set up later in this guide. 1. To create a public hosted zone, follow the instructions in [Creating a public hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html) in the Amazon Route 53 documentation. @@ -143,7 +153,7 @@ To create a public certificate using the AWS Certificate Manager, you must first ![Certificate that is pending validation](https://assets.ubuntu.com/v1/5caeac31-manage_tls_cname-record.png) 1. To validate the certificate, follow the instructions in [Validating domain ownership](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html) in the AWS Certificate Manager documentation. - Since you have a public hosted zone for your domain in Amazon Route 53 (see [step 1](#h-1-configure-routing-information-and-name-servers-8)), you can follow the steps for creating records in Route 53. + Since you have a public hosted zone for your domain in Amazon Route 53 (see {ref}`sec-configure-routing-info-name-servers`), you can follow the steps for creating records in Route 53. DNS propagation usually takes a while. When it completes and the validation is successful, the status of the certificate changes to issued, and it is ready to use. @@ -153,7 +163,7 @@ DNS propagation usually takes a while. When it completes and the validation is s To use the Anbox Cloud Appliance through your domain name, AWS must route the HTTPS traffic for your domain to the Anbox Cloud Appliance. To ensure this, you must create a load balancer that listens for traffic and routes it to the appliance. -1. Go to the [Load balancers](https://us-east-1.console.aws.amazon.com/ec2/home#LoadBalancers:) page in the EC2 dashboard. +1. Go to the Load balancers page in the EC2 dashboard. 1. Click **Create load balancer**. 1. Choose `Application Load Balancer` as the load balancer type. 1. For the **Basic configuration**, keep the default options (scheme: internet-facing, IP address type: `IPv4`). @@ -192,7 +202,7 @@ When the load balancer is created, AWS assigns it an automatic DNS name. The fol You now need to route the traffic that goes to your domain name to the load balancer. 1. Go to the [Route 53](https://console.aws.amazon.com/route53/) console. -1. Select your public hosted zone (which was created automatically if you registered your domain through Amazon Route 53, or which you created in [step 1](#h-1-configure-routing-information-and-name-servers-8) otherwise). +1. Select your public hosted zone (which was created automatically if you registered your domain through Amazon Route 53, or which you created earlier in {ref}`sec-configure-routing-info-name-servers`). 1. Create a type `A` DNS record that routes the traffic that from the public hosted zone to the load balancer: 1. Click **Create Record** and select `Simple routing`. diff --git a/howto/android/custom_vhal.md b/howto/android/custom-vhal.md similarity index 82% rename from howto/android/custom_vhal.md rename to howto/android/custom-vhal.md index c6e5b1e3..01a63cf3 100644 --- a/howto/android/custom_vhal.md +++ b/howto/android/custom-vhal.md @@ -1,14 +1,17 @@ +(howto-replace-anbox-vhal)= +# Replace the Anbox VHAL + *since 1.22.0* -[note type="information" status="Note"] -Replacing the Anbox VHAL is only supported on [AAOS images](https://discourse.ubuntu.com/t/24185). +```{note} +Replacing the Anbox VHAL is only supported on {ref}`AAOS images `. The Anbox Cloud dashboard does not support custom VHAL implementations. -[/note] +``` This document will guide through the process of replacing the Anbox Cloud VHAL implementation with your own implementation placed in the [ODM partition](https://source.android.com/docs/core/architecture/partitions/odm-partitions) -using an [addon](https://discourse.ubuntu.com/t/38727). +using {ref}`exp-addons`. ## Prerequisites @@ -34,7 +37,7 @@ property to `odm`. This will be done by writing that system property to the In the following example, we will name our addon `custom-vhal`. To override the VHAL implementation, we will use a -[pre-start hook](https://discourse.ubuntu.com/t/28555) which is executed +{ref}`pre-start hook ` which is executed before Android gets started. The directory layout for the addon is strict and must be: @@ -92,8 +95,7 @@ cp "${ADDON_DIR}/vhal.rc" "${ANDROID_ODM_DIR}/etc/init/" echo "ro.anbox.automotive.vhal=odm" >> "${ANDROID_ODM_DIR}/etc/build.prop" ``` -The addon -[`manifest.yaml`](https://discourse.ubuntu.com/t/25293) file +The {ref}`ref-addon-manifest` file contains metadata: ```yaml @@ -120,14 +122,13 @@ Anbox Cloud applications. If you plan to always override the Anbox Cloud VHAL implementation in all applications, you can -[enable the addon globally](https://discourse.ubuntu.com/t/25285): +enable the addon globally (see {ref}`howto-enable-addons-globally`): ```bash amc config set application.addons custom-vhal ``` -Otherwise, add it to your -[application manifest](https://discourse.ubuntu.com/t/24197): +Otherwise, add it to your {ref}`ref-application-manifest`: ```yaml name: my-app @@ -135,8 +136,8 @@ addons: - custom-vhal ``` -## Related information +## Related topics -- [Create an addon](https://discourse.ubuntu.com/t/25284) -- [How to use addons](https://discourse.ubuntu.com/t/17759) -- [How to extend an application](https://discourse.ubuntu.com/t/28554) +- {ref}`howto-create-addons` +- {ref}`howto-addons` +- {ref}`howto-extend-application` diff --git a/howto/android/graphics-debugging-with-renderdoc.md b/howto/android/graphics-debugging-with-renderdoc.md index 49c75345..a5ec8a40 100644 --- a/howto/android/graphics-debugging-with-renderdoc.md +++ b/howto/android/graphics-debugging-with-renderdoc.md @@ -1,3 +1,6 @@ +(howto-debug-graphics-renderdoc)= +# How to debug graphics with Renderdoc + [Renderdoc](https://github.com/baldurk/renderdoc) is a graphics frame debugger which supports Android applications. Debugging graphics can be challenging and [Renderdoc](https://github.com/baldurk/renderdoc) is a great tool to provide insight into Vulkan and OpenGL command execution. The following describes how you can use Renderdoc with Anbox Cloud. @@ -10,7 +13,7 @@ For capturing Android applications you need to install the Android SDK as Render ## Configure Renderdoc -Capturing applications running in Android with Renderdoc is not much different than what is described in [the official documentation](https://renderdoc.org/docs/how/how_android_capture.html). The most important part is to configure the path to the Android SDK in the Renderdoc settings. See [here](https://renderdoc.org/docs/window/settings_window.html#android-options) for more details. +Capturing applications running in Android with Renderdoc is not much different than what is described in [the official documentation](https://renderdoc.org/docs/how/how_android_capture.html). The most important part is to configure the path to the Android SDK in the Renderdoc settings. See [Android options](https://renderdoc.org/docs/window/settings_window.html#android-options) for more information. ## Configure Anbox @@ -26,10 +29,10 @@ The device will show up in the output of adb devices -You can find more information in [Access an instance](https://discourse.ubuntu.com/t/how-to-access-an-instance/17772). +See {ref}`howto-access-instance` for more information. -Renderdoc can only inject itself into applications which have debug mode turn on. See [here](https://renderdoc.org/docs/how/how_android_capture.html#how-do-i-use-renderdoc-on-android) for more details. +Renderdoc can only inject itself into applications which have debug mode turn on. See [How do I use RenderDoc on Android?](https://renderdoc.org/docs/how/how_android_capture.html#how-do-i-use-renderdoc-on-android) for more information. ## Capture a trace -Capturing a trace on Anbox Cloud is no different after the initial setup than on any other Android devices and you can follow the instructions [in the official documentation](https://renderdoc.org/docs/how/how_android_capture.html#). +Capturing a trace on Anbox Cloud is no different after the initial setup than on any other Android devices and you can follow the instructions [in the official documentation](https://renderdoc.org/docs/how/how_android_capture.html). diff --git a/howto/android/landing.md b/howto/android/landing.md index aac9c7db..65e2efa0 100644 --- a/howto/android/landing.md +++ b/howto/android/landing.md @@ -1,6 +1,12 @@ -The guides in this section describe how to work with Android in Anbox Cloud. +(howto-Android)= +# How to work with Android in Anbox Cloud -The following guides are available: +The following guides in this section describe how to work with Android in Anbox Cloud: -* [Graphics debugging with Renderdoc](https://discourse.ubuntu.com/t/how-to-debug-graphics-with-renderdoc/42427) -* [Replace the Anbox VHAL](https://discourse.ubuntu.com/t/replace-the-anbox-vhal/45070) +```{toctree} +:titlesonly: + +Debug graphics with Renderdoc +Create a virtual Android device +Replace the Anbox VHAL +``` diff --git a/howto/application/virtual-devices.md b/howto/android/virtual-devices.md similarity index 67% rename from howto/application/virtual-devices.md rename to howto/android/virtual-devices.md index abcdba3d..79ea1174 100644 --- a/howto/application/virtual-devices.md +++ b/howto/android/virtual-devices.md @@ -1,3 +1,6 @@ +(howto-create-virtual-device)= +# How to create a virtual Android device + In addition to running individual Android apps, Anbox Cloud allows you to stream the whole Android experience. The following sections describe how to set up such a virtual Android device experience. ## Set up an application for the virtual device @@ -27,9 +30,9 @@ resources: ## Optionally extend the application -If you want to install additional applications that you want to offer as part of the default virtual device, you can extend the application with [hooks](https://discourse.ubuntu.com/t/hooks/28555). For example, you could replace the standard Android launcher with a custom one or change the system locale. +If you want to install additional applications that you want to offer as part of the default virtual device, you can extend the application with {ref}`ref-hooks`. For example, you could replace the standard Android launcher with a custom one or change the system locale. -See [How to extend an application](https://discourse.ubuntu.com/t/extand-an-application/28554) for instructions. +See {ref}`howto-extend-application` for instructions on extending your application. ## Create the application @@ -37,6 +40,6 @@ Once the configuration is in place, create the application in AMS: amc application create vdev -After creating the application, you can stream it through the UI of the Anbox Stream Gateway (see [Get started with Anbox Cloud (web dashboard)](https://discourse.ubuntu.com/t/getting-started-with-anbox-cloud-web-dashboard/24958) for more details) or your own custom client application built with the [Anbox Streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8). +After creating the application, you can stream it through the UI of the Anbox Stream Gateway (see {ref}`tut-getting-started-dashboard`) or your own custom client application built with the Streaming SDK (see {ref}`sec-streaming-sdk`). ![Virtual device|690x662,100%](https://assets.ubuntu.com/v1/4cc5a115-application_virtual-device.png) diff --git a/howto/application/create.md b/howto/application/create.md index 2e8b84c3..86e7b9c0 100644 --- a/howto/application/create.md +++ b/howto/application/create.md @@ -1,10 +1,13 @@ +(howto-create-application)= +# How to create an application + An application can be created using the Anbox Cloud dashboard or through the CLI. Any application must be created first to be available on the Anbox Cloud cluster. The internal process will prepare an instance based on the currently available image with the application package installed. This instance is then used for any newly launched instances to support fast boot times. ## Prerequisites -To create a new application, you need an [application manifest](https://discourse.ubuntu.com/t/application-manifest/24197) and optionally an Android Package (APK) with support for target architecture. +To create a new application, you need an {ref}`ref-application-manifest` and optionally an Android Package (APK) with support for target architecture. The application manifest is a `yaml` file and is used to define various attributes of your application. @@ -67,13 +70,15 @@ If you are using a tarball file, compress the file with bzip2 and use the same c tar cvjf foo.tar.bz2 -C app.apk extra-data manifest.yaml -[note type="information" status="Note"]Due to Snap strict confinement, the directory/zip archive/tarball must be located in the home directory.[/note] +```{note} +Due to Snap strict confinement, the directory/zip archive/tarball must be located in the home directory. +``` When you are ready, run: amc application create -When the `create` command returns, the application package is uploaded to the Anbox Management Service (AMS) which starts the [bootstrap process](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2). +When the `create` command returns, the application package is uploaded to the Anbox Management Service (AMS) which starts the bootstrap process. Remember that the application is not yet ready to be used. You can watch the status of the application with the following command: @@ -121,4 +126,8 @@ resources: disk-size: 8GB ``` -Once the status of the application switches to `ready`, the application is ready and can be used. See [How to wait for an application](https://discourse.ubuntu.com/t/wait-for-an-application/24202) for information about how to monitor the application status. +Once the status of the application switches to `ready`, the application is ready and can be used. See {ref}`howto-wait-for-application` for information about how to monitor the application status. + +## Related topics + +* {ref}`sec-application-bootstrap` \ No newline at end of file diff --git a/howto/application/delete.md b/howto/application/delete.md index 501dc59e..76db51e3 100644 --- a/howto/application/delete.md +++ b/howto/application/delete.md @@ -1,3 +1,6 @@ +(howto-delete-application)= +# How to delete an application + When an application is no longer needed, it can be fully removed from Anbox Cloud. Removing an application will cause all of its versions to be removed, including all of its currently active instances. Be extra careful as this might affect your users if any are still using instances of the application you want to remove. Once you're sure you want to remove the application, you can do so with the following command: diff --git a/howto/application/extend.md b/howto/application/extend.md index f38307c6..4c570404 100644 --- a/howto/application/extend.md +++ b/howto/application/extend.md @@ -1,29 +1,31 @@ -You can extend an application either by adding [hooks](#application-hooks) directly to the application or by creating an [addon](#addon) that includes one or more hooks and adding it to the application. +(howto-extend-application)= +# How to extend an application + +You can extend an application either by adding hooks directly to the application or by creating an addon that includes one or more hooks and adding it to the application. * If you want to extend one application only, you should use application hooks. They are easy and quick to set up and do not require creating an addon. * If your extension contains common functionality that you want to share among multiple applications, you should create an addon that includes one or more hooks. You can then add the addon to all applications that should use the functionality. For both options, you must create one or more hooks first. The options differ in how you add these hooks to your application. +(sec-create-hook)= ## Create a hook -A hook is a script file that runs a series of commands at a specific time in the application life cycle. See [Hooks](https://discourse.ubuntu.com/t/hooks/28555) for detailed information. +A hook is a script file that runs a series of commands at a specific time in the application life cycle. See {ref}`ref-hooks` for more information. The general steps for creating a hook are as follows: 1. Create or download any files or applications that the hook needs. For example, this could be configuration files or Android applications that you want to run. 1. In a `hooks/` sub-directory, create a script file with the commands that you want to run. As the file name, use the name of the hook. - [note type="information" status="Tip"] + ```{tip} - Supported hooks are `pre-start`, `post-start` and `post-stop`. - Use the `INSTANCE_TYPE` variable to distinguish between regular and base instances. - - See [Hooks](https://discourse.ubuntu.com/t/hooks/28555) for more information. - [/note] + ``` 1. Make the hook file executable. -You must then add the hook file to your application, either [as an application hook](#application-hooks) or [through an addon](#addon). +You must then add the hook file to your application, either as an application hook or through an addon. The following sections give some examples for hooks. @@ -56,9 +58,9 @@ Complete the following steps to create a hook that changes the Android system lo sleep 5 ``` - [note type="information" status="Important"] - In the file, replace `` with the [environment variable](https://discourse.ubuntu.com/t/hooks/28555#environment-variables-1) that points to the current working directory for the hook. If you plan to run the hook [as an application hook](#application-hooks), use `$APP_DIR`. If you plan to run the hook [through an addon](#addon), use `$ADDON_DIR`. - [/note] + ```{important} + In the file, replace `` with the environment variable (see {ref}`sec-env-variables`) that points to the current working directory for the hook. If you plan to run the hook as an application hook, use `$APP_DIR`. If you plan to run the hook through an addon, use `$ADDON_DIR`. + ``` 1. Make all files in the `hooks` directory executable: cd .. && chmod +x hooks/* @@ -97,14 +99,13 @@ Complete the following steps to create a hook that replaces the standard Android sleep 20 ``` - [note type="information" status="Important"] - In the file, replace `` with the [environment variable](https://discourse.ubuntu.com/t/hooks/28555#environment-variables-1) that points to the current working directory for the hook. If you plan to run the hook [as an application hook](#application-hooks), use `$APP_DIR`. If you plan to run the hook [through an addon](#addon), use `$ADDON_DIR`. - [/note] + ```{important} + In the file, replace `` with the environment variable that points to the current working directory for the hook. If you plan to run the hook as an application hook, use `$APP_DIR`. If you plan to run the hook through an addon, use `$ADDON_DIR`. + ``` 1. Make all files in the `hooks` directory executable: cd .. && chmod +x hooks/* - ## Use hooks in an application You can add your hooks directly to an application. To do so, complete the following steps: @@ -119,7 +120,7 @@ You can add your hooks directly to an application. To do so, complete the follow disk-size: 3GB ``` -1. Prepare one or more hooks as described in [Create a hook](#create-a-hook-1). +1. Prepare one or more hooks as described in {ref}`sec-create-hook`. 1. Move the `hooks` directory and any other files that are required by the hook into the `app` directory. The folder structure should look like this: @@ -137,16 +138,15 @@ You can add your hooks directly to an application. To do so, complete the follow After the application is created, launch an instance. You should see that the hook is executed and that, for example, the system locale is changed or the standard Android launcher is replaced. -[note type="information" status="Important"] -By default, the files required for the hooks (for example, APK files) are removed automatically from the application image after the [application bootstrap](https://discourse.ubuntu.com/t/17760) is completed. According to your application requirements, consider using the [`bootstrap.keep`](https://discourse.ubuntu.com/t/application-manifest/24197#bootstrap-process-2) attribute in the application manifest file if you want to keep any content needed by the application running in a regular instance. -[/note] +```{important} +By default, the files required for the hooks (for example, APK files) are removed automatically from the application image after the application bootstrap is completed. According to your application requirements, consider using the `bootstrap.keep` attribute in the application manifest file if you want to keep any content needed by the application running in a regular instance. See {ref}`sec-application-manifest-bootstrap` for more information. +``` - ## Create an addon with hooks If you want to use your hooks in multiple applications, you should include them in an addon. To do so, complete the following steps: -1. In a new `my-addon` directory, prepare one or more hooks as described in [Create a hook](#create-a-hook-1). +1. In a new `my-addon` directory, prepare one or more hooks as described in {ref}`sec-create-hook`. 1. Create a `manifest.yaml` file in the `my-addon` directory with the following content: ``` @@ -180,4 +180,6 @@ addons: [my-addon] The application will now execute the hook and you should see that, for example, the system locale is changed or the standard Android launcher is replaced. -For more information, see [Create an addon](https://discourse.ubuntu.com/t/creating-an-addon/25284) and the [addon reference guide](https://discourse.ubuntu.com/t/addons/25293). +## Related topics +* {ref}`exp-addons` +* {ref}`howto-create-addons`. diff --git a/howto/application/landing.md b/howto/application/landing.md index 8cf0f69a..5598042f 100644 --- a/howto/application/landing.md +++ b/howto/application/landing.md @@ -1,15 +1,21 @@ -The guides in this section describe how to create and work with your applications. +(howto-manage-applications)= +# How to manage applications -See [Applications](https://discourse.ubuntu.com/t/managing-applications/17760) for an introduction to how applications are used in Anbox Cloud. To check which configuration options are available for applications, see [Application manifest](https://discourse.ubuntu.com/t/application-manifest/24197). +The guides in this section describe how to manage your applications. + +See {ref}`exp-applications` for an introduction to how applications are used in Anbox Cloud. To check which configuration options are available for applications, see {ref}`ref-application-manifest`. The following how-to guides are available for operations on applications: -* [Create an application](https://discourse.ubuntu.com/t/how-to-create-an-application/24198) -* [Delete an application](https://discourse.ubuntu.com/t/how-to-delete-an-application/24199) -* [Extend an application](https://discourse.ubuntu.com/t/how-to-extend-an-application/28554) -* [List applications](https://discourse.ubuntu.com/t/how-to-list-applications/24200) -* [Stream an application](https://discourse.ubuntu.com/t/how-to-stream-applications/42688) -* [Test an application](https://discourse.ubuntu.com/t/how-to-test-your-application/17775) -* [Update an application](https://discourse.ubuntu.com/t/how-to-update-an-application/24201) -* [Pass custom data to an application](https://discourse.ubuntu.com/t/how-to-pass-custom-data-to-an-application/30368) -* [Wait for an application](https://discourse.ubuntu.com/t/how-to-wait-for-an-application/24202) +```{toctree} +:titlesonly: +Create an application +Delete an application +Extend an application +List applications +Stream applications +Test an application +Update an application +Pass custom data to an application +Wait for an application +``` diff --git a/howto/application/list.md b/howto/application/list.md index d1937a19..f25a49e9 100644 --- a/howto/application/list.md +++ b/howto/application/list.md @@ -1,3 +1,6 @@ +(howto-list-applications)= +# How to list applications + To list all available applications, use the following command: amc application ls @@ -10,7 +13,7 @@ The filter flag accepts a key-value pair as input for the filter. The following Name | Value ----------------|------------ -`instance-type` | Supported instance type. See [Instance types](https://discourse.ubuntu.com/t/application-manifest/24197#instance-type-1) for a list of available instance types. This attribute is deprecated since 1.20 and will be removed in future releases. +`instance-type` | Supported instance type. See {ref}`sec-application-manifest-instance-type` for a list of available instance types. This attribute is deprecated since 1.20 and will be removed in future releases. `addons` | Comma-separated list of addons. `tag` | Application tag name (deprecated, use `tags` instead). `tags` | Comma-separated list of tags. diff --git a/howto/application/userdata.md b/howto/application/pass-custom-data.md similarity index 96% rename from howto/application/userdata.md rename to howto/application/pass-custom-data.md index 8ad06354..93703930 100644 --- a/howto/application/userdata.md +++ b/howto/application/pass-custom-data.md @@ -1,3 +1,6 @@ +(howto-pass-custom-data-application)= +# How to pass custom data to an application + You can pass custom data to your application, which you can then use in addons or hooks. For example, you might want to pass user IDs, application configuration or display settings. The user data that you pass in is stored in the `/var/lib/anbox/userdata` file in the instance, and your hooks can access it from this file. diff --git a/howto/application/stream.md b/howto/application/stream.md index ab639834..2f015638 100644 --- a/howto/application/stream.md +++ b/howto/application/stream.md @@ -1,3 +1,6 @@ +(howto-stream-applications)= +# How to stream applications + You can stream applications using the Anbox Cloud dashboard or your custom stream client. You can also stream applications by launching an instance with streaming enabled, using the `amc` CLI. ## Using the CLI @@ -19,11 +22,11 @@ For example, to create an instance with a 1080p resolution, a frame rate of 60 a ## Using the dashboard -The dashboard has in-browser streaming capabilities through WebRTC. It uses the [Streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8). +The dashboard has in-browser streaming capabilities through WebRTC. It uses the {ref}`sec-streaming-sdk`. You can start a streaming session for any of the successfully created applications. An application is ready to be streamed when its *Status* is *Ready*. When you select the *Start a new session* icon for an application, you can specify the desired streaming attributes such as the screen resolution, frame rate, screen orientation before launching the session. -To understand how the streaming stack of Anbox Cloud works, see [About application streaming](https://discourse.ubuntu.com/t/streaming-android-applications/17769). +To understand how the streaming stack of Anbox Cloud works, see {ref}`exp-application-streaming`. ### Streaming statistics @@ -55,8 +58,7 @@ The downloaded `.csv` file has the following statistics: Use the **Sharing** button on the session page to share a streaming session with users without an account. The button generates a link using which users without an account can join your session. -## Related information +## Related topics -* [Application Streaming](https://discourse.ubuntu.com/t/application-streaming/17769) -* [How to access the stream gateway](https://discourse.ubuntu.com/t/how-to-access-the-stream-gateway/17784) -* [Set up a stream client](https://discourse.ubuntu.com/t/set-up-a-stream-client/37328) +* {ref}`tut-set-up-stream-client` +* {ref}`howto-access-stream-gateway` diff --git a/howto/application/test.md b/howto/application/test.md index 9189bf47..705184ab 100644 --- a/howto/application/test.md +++ b/howto/application/test.md @@ -1,4 +1,7 @@ -Anbox Cloud enables you to run automated tests for Android applications at scale. In the following example, we make use of [Appium](http://appium.io/) to interact with an [instance](https://discourse.ubuntu.com/t/26204#instance) running on Anbox Cloud and automate UI testing for Android applications. +(howto-test-application)= +# How to test your application + +Anbox Cloud enables you to run automated tests for Android applications at scale. In the following example, we make use of [Appium](http://appium.io/) to interact with an instance running on Anbox Cloud and automate UI testing for Android applications. ## Setup Anbox Cloud for Appium @@ -12,13 +15,17 @@ This will create an instance which exposes the TCP port `5559` on its private ad amc launch -s +adb --enable-graphics -r -[note type="information" status="Tip"]If you're wondering about the syntax of the command used to launch an instance, see [How to launch an instance](https://discourse.ubuntu.com/t/24327).[/note] +```{tip} +If you're wondering about the syntax of the command used to launch an instance, see {ref}`howto-create-instance`. +``` -If you want to run the Appium tests against an Android application managed by AMS (see [How to create an application](https://discourse.ubuntu.com/t/create-an-application/24198)) you can start a regular instance instead: +If you want to run the Appium tests against an Android application managed by AMS (see {ref}`howto-create-application`) you can start a regular instance instead: amc launch -s adb --enable-graphics --disable-watchdog app -[note type="information" status="Important"]The `--disable-watchdog` argument is important because by default, Anbox prevents Android from switching its foreground application and terminates when the application is stopped. To prevent this, we need to disable the watchdog.[/note] +```{important} +The `--disable-watchdog` argument is important because by default, Anbox prevents Android from switching its foreground application and terminates when the application is stopped. To prevent this, we need to disable the watchdog. +``` Once the instance is up and running, you can get its private IP address and the exposed port for the ADB service endpoint with the `amc ls` command: @@ -55,11 +62,11 @@ You should see output similar to the following: connected to localhost:10000 ``` -[note type="caution" status="Warning"] +```{caution} Appium uses ADB as located in the Android SDK to establish a connection between the remote Android instance and the ADB daemon running on your machine. As mixing different versions of ADB is not supported you need to use ADB from the Android SDK in all cases. If you have the `adb` client installed from other sources, like the Ubuntu package archive, remove it first: `sudo apt purge -y adb` -[/note] +``` ## Execute Tests with Appium @@ -87,7 +94,7 @@ For more details about Appium, please refer to the [Appium official documentatio ### APK managed by AMS -If you want to run test cases without installing the APK every time when starting a new test session in Appium, you can let AMS manage the application for you. See [About applications](https://discourse.ubuntu.com/t/managing-applications/17760) for more details. +If you want to run test cases without installing the APK every time when starting a new test session in Appium, you can let AMS manage the application for you. See {ref}`exp-applications` for more information. In this example we use the following application `manifest.yaml`: @@ -103,7 +110,9 @@ Once the application is fully bootstrapped by AMS, you can launch an instance fo amc launch -s +adb --enable-graphics --disable-watchdog app -[note type="information" status="Note"]Use the `--vm` option to launch a VM instance.[/note] +```{note} +Use the `--vm` option to launch a VM instance. +``` After the instance is up and running, you need to specify the proper `appPackage` and `appActivity` in the Appium preset, the installed Android application will be launched automatically in the instance when a new session is created by Appium. diff --git a/howto/application/update.md b/howto/application/update.md index e6dfa3fc..dd73ac1c 100644 --- a/howto/application/update.md +++ b/howto/application/update.md @@ -1,3 +1,6 @@ +(howto-update-application)= +# How to update an application + Updating an existing application works similar to creating a new one. Each time an existing application is updated, it is extended with a new version. All versions that an application currently has are individually usable, but only one can be launched at a time. When you want to update an existing application with a new manifest or APK, provide both in the same format as when the application was created. The `amc application update` command accepts both a directory and an absolute file path. @@ -82,11 +85,12 @@ resources: Each version gets a monotonically increasing number assigned (here we have version `0` and version `1`). In addition, each version has a status which indicates the status of the bootstrap process AMS is performing for it. Once an application version is marked as `active`, it is ready to be used. +(sec-publish-app-versions)= ## Publish application versions The most important part of an application version is the `published` field. If a version is marked as published, it is available to launch and use. Generally when launching instances by using the AMS REST API, if no specific application version is given, by default, the latest published version of an application is used to create the instance. -If [`application.auto_publish`](https://discourse.ubuntu.com/t/ams-configuration/20872) is set to `true` (the default), new versions are automatically published. Otherwise, you need to publish them manually. +If `application.auto_publish` (in {ref}`ref-ams-configuration`) is set to `true` (the default), new versions are automatically published. Otherwise, you need to publish them manually. You can mark an application version as published with the following command: @@ -106,6 +110,7 @@ Each version takes up space on the LXD nodes. To free up space and remove old an The command will ask for your approval before the version is removed as it might affect your users. If you want to bypass the check, you can add the `--yes` flag to the command. +(sec-configure-automatic-app-updates)= ## Configure automatic application updates AMS automatically updates an application whenever any of its dependencies (parent image, addons, global configuration) changes. This produces a new version for the application, which is automatically published if the `application.auto_publish` configuration item is enabled. diff --git a/howto/application/wait.md b/howto/application/wait.md index d8f10d40..4e0c3e48 100644 --- a/howto/application/wait.md +++ b/howto/application/wait.md @@ -1,17 +1,20 @@ +(howto-wait-for-application)= +# How to wait for an application + The `amc wait` command instructs AMS to wait for an application to reach a specific condition. If the condition is not satisfied within the specified time (five minutes by default), a timeout error will be returned by AMS. The supported conditions for an application are as follows: Name | Value ----------------|------------ -`instance-type` | Supported instance type. See [Instance types](https://discourse.ubuntu.com/t/application-manifest/24197#instance-type-1) for a list of available instance types. This attribute is deprecated since 1.20 and will be removed in future releases. +`instance-type` | Supported instance type. See {ref}`sec-application-manifest-instance-type` for a list of available instance types. This attribute is deprecated since 1.20 and will be removed in future releases. `addons` | Comma-separated list of addons. `tag` | Application tag name (deprecated, use `tags` instead). `tags` | Comma-separated list of tags. `published` | "true" or "false" indicating whether the application is published. `immutable` | "true" or "false" indicating whether the application is changeable. -`status` | Application status, possible values: `error`, `unknown`, `initializing`, `ready`, `deleted`. See [Possible application status](https://discourse.ubuntu.com/t/applications/17760) for more information. +`status` | Application status, possible values: `error`, `unknown`, `initializing`, `ready`, `deleted`. See {ref}`sec-application-status` for more information. -One example of using the `amc wait` command is to wait for the application [bootstrap process](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2) to be done, since the application bootstrap is performed asynchronously by the AMS service and takes some time to process. The application cannot be used until the bootstrap is complete and the status is marked as `ready`. +One example of using the `amc wait` command is to wait for the application bootstrap process to be done, since the application bootstrap is performed asynchronously by the AMS service and takes some time to process. The application cannot be used until the bootstrap is complete and the status is marked as `ready`. amc wait -c status=ready bcmap7u5nof07arqa2ag diff --git a/howto/cluster/configure-nodes.md b/howto/cluster/configure-nodes.md index 247dd785..3fbe2d45 100644 --- a/howto/cluster/configure-nodes.md +++ b/howto/cluster/configure-nodes.md @@ -1,3 +1,6 @@ +(howto-configure-cluster-nodes)= +# How to configure cluster nodes + Your cluster or multi-node appliance might contain nodes with different resources and different capacity. Therefore, each node can be configured separately. ## Show node configuration @@ -27,12 +30,12 @@ config: gpu-encoder-slots: 0 tags: [] ``` - +(sec-config-allocation-rates)= ## Configure allocation rates AMS allows over-committing available resources on a node. This mechanism improves resource usage, because usually, instances don't use 100% of their dedicated resources all of the time. -By default, AMS uses a CPU allocation rate of `4` and a memory allocation rate of `2`. See [Over-committing](https://discourse.ubuntu.com/t/about-capacity-planning/28717#over-committing-resources-3) for more information. +By default, AMS uses a CPU allocation rate of `4` and a memory allocation rate of `2`. See {ref}`sec-over-committing` for more information. You can configure the allocation rates with the `cpu-allocation-rate` and `memory-allocation-rate` configuration items. @@ -43,19 +46,22 @@ Use the following commands to set the allocation rates on a node (for example, ` ## Configure if a node can accept new instances -[note type="information" status="Note"]Currently Anbox Cloud does not support GPUs for virtual machine instances. This feature is planned for a future release.[/note] +```{note} +Currently Anbox Cloud does not support GPUs for virtual machine instances. This feature is planned for a future release. +``` -You can configure a node to stop accepting new instances. This is especially important in certain scenarios such as [scaling down a LXD cluster](https://discourse.ubuntu.com/t/how-to-scale-down-a-lxd-cluster/24323). When you want to remove a node from the LXD cluster, the node must not have any instances. Hence, all running instances must be removed or disconnected and AMS must stop considering the node for new instances. +You can configure a node to stop accepting new instances. This is especially important in certain scenarios such as scaling down a LXD cluster. When you want to remove a node from the LXD cluster, the node must not have any instances. Hence, all running instances must be removed or disconnected and AMS must stop considering the node for new instances. See {ref}`howto-scale-down-cluster` for instructions on scaling down a cluster. Use the following command to prevent the node from accepting new instances: amc node set unschedulable true +(sec-config-gpu-slots)= ## Configure GPU slots and GPU encoder slots -GPU slots are used to share GPUs amongst instances. See [GPUs and instances](https://discourse.ubuntu.com/t/17768) and [GPU slots](https://discourse.ubuntu.com/t/about-capacity-planning/28717#gpu-slots-2) for more information. +GPU slots are used to share GPUs amongst instances. See {ref}`exp-gpus-instances` and {ref}`sec-gpu-slots` for more information. -Each GPU-equipped cluster node is configured with a number of GPU slots and a number of GPU encoder slots. See [Node-specific configuration](https://discourse.ubuntu.com/t/ams-configuration/20872#node-specific-configuration-1) for the default values that are used. Nodes without GPU are configured with 0 GPU slots and 0 GPU encoder slots. +Each GPU-equipped cluster node is configured with a number of GPU slots and a number of GPU encoder slots. See {ref}`sec-node-configuration` for the default values that are used. Nodes without GPU are configured with 0 GPU slots and 0 GPU encoder slots. Use the following commands to change the number of GPU slots and GPU encoder slots for a node: @@ -71,6 +77,7 @@ Use the following commands to set the number of GPU slots and GPU encoder slots Replace `` with the node name (for example, `lxd0`), `` with the GPU number and `` with the number of slots. +(sec-tags)= ## Tags A node can have a set of tags which can be used for different purposes. Use the following command to set the tags for a specific node: diff --git a/howto/cluster/landing.md b/howto/cluster/landing.md index 59afed2f..f7c0a54b 100644 --- a/howto/cluster/landing.md +++ b/howto/cluster/landing.md @@ -1,11 +1,19 @@ +(howto-manage-cluster)= +# How to manage cluster nodes + The guides in this section describe how to distribute the load of your Anbox Cloud installation over several machines in a cluster. -For full Anbox Cloud deployments: +See {ref}`exp-clustering` for an introduction to how clustering works in Anbox Cloud. -* [How to configure cluster nodes](https://discourse.ubuntu.com/t/configure-cluster-nodes/28716) -* [How to scale up a LXD cluster](https://discourse.ubuntu.com/t/scale-up-a-lxd-cluster/24322) -* [How to scale down a LXD cluster](https://discourse.ubuntu.com/t/scale-down-a-lxd-cluster/24323) +```{important} +Currently, Anbox Cloud Appliance does not support clustering. +``` +The following how-to guides are available for operations related to clustering in regular Anbox Cloud deployments: -See [About clustering](https://discourse.ubuntu.com/t/capacity-planning/17765) for an introduction to how clustering works in Anbox Cloud. +```{toctree} +:titlesonly: -[note type="information" status="Important"]Currently, Anbox Cloud Appliance does not support clustering.[/note] +Configure cluster nodes +Scale down a cluster +Scale up a cluster +``` diff --git a/howto/cluster/scale-down.md b/howto/cluster/scale-down.md index 7adb6fdf..0c67b0af 100644 --- a/howto/cluster/scale-down.md +++ b/howto/cluster/scale-down.md @@ -1,3 +1,6 @@ +(howto-scale-down-cluster)= +# How to scale down a LXD cluster + Scaling down a LXD cluster involves more checks than scaling up. There are two important requirements when scaling down: diff --git a/howto/cluster/scale-up.md b/howto/cluster/scale-up.md index fe4e6766..43056292 100644 --- a/howto/cluster/scale-up.md +++ b/howto/cluster/scale-up.md @@ -1,3 +1,6 @@ +(howto-scale-up-cluster)= +# How to scale up a LXD cluster + Scaling up a LXD cluster can be achieved via Juju. Juju automates the deployment of the individual units and links them together. Adding additional LXD units or removing existing ones is not an instant operation. Adding a new node, for example, can take 5-10 minutes and must be planned in advance. The deployment of a single node will include the following steps: diff --git a/howto/manage/web-dashboard.md b/howto/dashboard/landing.md similarity index 70% rename from howto/manage/web-dashboard.md rename to howto/dashboard/landing.md index ea0fb19f..de806382 100644 --- a/howto/manage/web-dashboard.md +++ b/howto/dashboard/landing.md @@ -1,4 +1,6 @@ -The Anbox Cloud Dashboard offers a web GUI that users can use to create, manage and stream applications from their web browser. If you have configured the [Anbox Application Registry (AAR)](https://discourse.ubuntu.com/t/application-registry/17761), you can also view applications in the registry using the **Registry** button on the main menu. You can use the pre-installed dashboard almost immediately after deploying Anbox Cloud. +(howto-use-web-dashboard)= +# How to use the web dashboard +The Anbox Cloud Dashboard offers a web GUI that users can use to create, manage and stream applications from their web browser. If you have configured the Anbox Application Registry (AAR), you can also view applications in the registry using the **Registry** button on the main menu. You can use the pre-installed dashboard almost immediately after deploying Anbox Cloud. ## Prerequisites @@ -25,10 +27,10 @@ unit-anbox-cloud-dashboard-0: enqueued: 2021-02-10 14:04:44 +0000 UTC started: 2021-02-10 14:04:44 +0000 UTC ``` - +(sec-register-ubuntu-one-appliance)= ### Register an Ubuntu One account in Anbox Cloud Appliance -If you followed the instructions in the [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/install-appliance/22681) tutorial or in [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702), you already registered your Ubuntu One account. +If you followed the instructions in the {ref}`tut-installing-appliance` tutorial, you already registered your Ubuntu One account. To add more accounts, use the following command: @@ -41,3 +43,8 @@ The generated link is valid for one hour. ## Using the dashboard To access the dashboard, go to `https:///`. The dashboard uses self-signed certificates. You might see a warning from your browser and have to accept the certificates manually. + +## Related topics + +* {ref}`exp-aar` +* {ref}`exp-web-dashboard` diff --git a/howto/install-appliance/aws.md b/howto/install-appliance/aws.md index 2348baef..d19acf82 100644 --- a/howto/install-appliance/aws.md +++ b/howto/install-appliance/aws.md @@ -1,13 +1,16 @@ +(howto-install-appliance-aws)= +# How to install the appliance on AWS + You can install the Anbox Cloud Appliance on AWS in one of two ways: - Install through the AWS Marketplace. This is the recommended way, because this method simplifies the installation and deployment process and allows billing to be handled directly through AWS. -- Install the Anbox Cloud Appliance snap on an AWS machine. This method is not recommended, but if you want to do it anyway, see the [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/install-appliance/22681) tutorial for instructions on how to install the snap. +- Install the Anbox Cloud Appliance snap on an AWS machine. This method is not recommended, but if you want to do it anyway, see the {ref}`tut-installing-appliance` tutorial for instructions on how to install the snap. The following instructions guide you through all relevant steps to deploy the Anbox Cloud Appliance from the AWS Marketplace. For additional information, see the [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) about launching an instance. The entire deployment process will take 10-15 minutes, depending on the selected hardware and the network conditions. -## Before you start +## Prerequisites Deploying the Anbox Cloud Appliance requires some familiarity with AWS. In particular, you should be familiar with: @@ -26,7 +29,9 @@ AWS supports running the Anbox Cloud Appliance both on [AWS Graviton](https://aw * AWS Graviton (Arm) and x86 offer equal performance for Android applications. * GPUs are available for both x86 and AWS Graviton (Arm). - [note type="information" status="Note"]To use GPUs with AWS Graviton (Arm), you must select a [G5g instance](https://aws.amazon.com/de/ec2/instance-types/g5g/). This instance type might not be available in all regions.[/note] + ```{note} + To use GPUs with AWS Graviton (Arm), you must select a [G5g instance](https://aws.amazon.com/de/ec2/instance-types/g5g/). This instance type might not be available in all regions. + ``` * Not all Android applications support the x86 ABI. Therefore, some applications can run only on Arm. For detailed information about the offering, see the following pages on the AWS Marketplace: @@ -34,15 +39,19 @@ For detailed information about the offering, see the following pages on the AWS * [Anbox Cloud Appliance for AWS Graviton (Arm)](https://aws.amazon.com/marketplace/pp/prodview-aqmdt52vqs5qk) * [Anbox Cloud Appliance for x86](https://aws.amazon.com/marketplace/pp/prodview-3lx6xyaapstz4) -### Check the prerequisites +### Hardware requirements + +Check the hardware requirements listed in {ref}`ref-requirements` for the Anbox Cloud Appliance. -Check the hardware requirements for the Anbox Cloud Appliance [here](https://discourse.ubuntu.com/t/requirements/17734#anbox-cloud-appliance-4). +### Required accounts -In addition, make sure you have the following accounts: +Make sure you have the following accounts: -* An Ubuntu SSO account. If you don't have one yet, create it [here](https://login.ubuntu.com). +* An Ubuntu SSO account. If you don't have one yet, [create it](https://login.ubuntu.com). * An AWS account that you use to buy a subscription to the Anbox Cloud Appliance. - [note type="information" status="Note"]The quota for your AWS account must be sufficient for the instance types that you plan to use.[/note] + ```{note} + The quota for your AWS account must be sufficient for the instance types that you plan to use. + ``` ## Install the appliance @@ -72,7 +81,7 @@ You will be presented with the pricing information. Click **Continue** to confir AWS offers various instance types. The Anbox Cloud Appliance images are supported for a subset of the available instance types only. -In the **Instance type** section, select the instance type that is most suitable for what you're planning to do. For example, if you just want to try out the Anbox Cloud Appliance, an instance type with GPU support and limited CPU and memory is sufficient. See the [Requirements](https://discourse.ubuntu.com/t/installation-requirements/17734#anbox-cloud-appliance-4) for the minimum hardware requirements. +In the **Instance type** section, select the instance type that is most suitable for what you're planning to do. For example, if you just want to try out the Anbox Cloud Appliance, an instance type with GPU support and limited CPU and memory is sufficient. See {ref}`sec-minimum-hardware-requirements`. ![Choose an instance type](https://assets.ubuntu.com/v1/e967ac16-install_appliance_instance-type.png) @@ -90,7 +99,7 @@ You do not need to customise any of the settings in the **Network settings** sec To allow external access, several ports in the security group attached to the AWS instance must be open. The AMI already comes with the required configuration, so you don't need to do any changes. However, for security reasons, you might want to limit access to specific source IPs or subnets. -For reference, all required ports are documented [here](https://discourse.ubuntu.com/t/requirements/17734). +For reference, all required ports are documented in {ref}`ref-requirements`. ![Configure the security group](https://assets.ubuntu.com/v1/f0af08ae-install_appliance_security-group.png) @@ -138,7 +147,7 @@ Connect to the virtual machine hosting the appliance using SSH. To do so, use th ## Finish the installation -Perform the following steps to finish the appliance installation on the virtual machine. If you are not already familiar with how to perform these steps, see the [tutorial on installing the appliance](https://discourse.ubuntu.com/t/22681) for detailed instructions. +Perform the following steps to finish the appliance installation on the virtual machine. If you are not already familiar with how to perform these steps, see {ref}`tut-installing-appliance` for detailed instructions. 1. Initialise the appliance 1. Register your Ubuntu SSO account with the appliance dashboard diff --git a/howto/install-appliance/azure.md b/howto/install-appliance/azure.md index 75b12fc7..8a86884e 100644 --- a/howto/install-appliance/azure.md +++ b/howto/install-appliance/azure.md @@ -1,3 +1,6 @@ +(howto-install-appliance-azure)= +# How to install the appliance on Azure + The Anbox Cloud Appliance is not yet available from the Azure Marketplace. However, you can install the Anbox Cloud Appliance snap on an Azure machine. ## Deploy using a quickstart template @@ -6,28 +9,34 @@ An [Azure quickstart template](https://github.com/Azure/azure-quickstart-templat Once you have completed the [deployment steps](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/canonical/anbox#deployment-steps), finish the installation by performing the following steps: -1. [Initialise the appliance](https://discourse.ubuntu.com/t/install-the-anbox-cloud-appliance-on-a-dedicated-machine/22681#initialise-the-appliance-6) -1. [Register your Ubuntu SSO account with the appliance dashboard](https://discourse.ubuntu.com/t/install-the-anbox-cloud-appliance-on-a-dedicated-machine/22681#register-with-the-dashboard-9). +1. {ref}`Initialise the appliance ` +1. {ref}`Register your Ubuntu SSO account with the appliance dashboard `. - [note type="information" status="Tip"]The output from the template will contain the public IP address of the VM that is required to complete this step.[/note] + ```{Tip} + The output from the template will contain the public IP address of the VM that is required to complete this step. + ``` ## Deploy manually An alternate option to using the quickstart template is to deploy manually. If you wish to deploy Anbox Cloud Appliance manually on Azure, the following instructions guide you through all relevant steps. -[details=Click here for details] +
+Click for details The entire deployment process will take 20-30 minutes, depending on the selected hardware and the network conditions. ### Prerequisites -Check the hardware requirements for the Anbox Cloud Appliance [here](https://discourse.ubuntu.com/t/requirements/17734#anbox-cloud-appliance-4). +Check the hardware requirements listed in {ref}`ref-requirements` for the Anbox Cloud Appliance. In addition, make sure you have the following prerequisites: * An Ubuntu SSO account. If you don't have one yet, create it [here](https://login.ubuntu.com). -* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to https://ubuntu.com/pro to retrieve it. - [note type="caution" status="Warning"]The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an *Ubuntu Pro* subscription.[/note] +* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to [Ubuntu Pro](https://ubuntu.com/pro) to retrieve it. + +```{caution} + The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an *Ubuntu Pro* subscription. +``` * An Azure account that you use to create the virtual machine. Once you have the prerequisites, the first step is to create a virtual machine on which you can install the Anbox Cloud Appliance. @@ -47,7 +56,7 @@ In the Quickstart Center, select **Deploy a virtual machine**. On the resulting On the **Basics** tab of the virtual machine configuration, specify the required information. Several of the options are specific to how and where you want to deploy your virtual machine. In most cases you can keep the default values, but make sure to set the following configurations: * Select the latest Ubuntu image (Ubuntu Server 22.04 LTS) for the architecture that you want to use. The following instructions and screenshots use the Arm64 architecture. -* Select a size that matches the [hardware requirements](https://discourse.ubuntu.com/t/requirements/17734#anbox-cloud-appliance-4). For example, select `Standard_D16ps_v5`, which has 16 vCPUs and 64 GB of RAM. +* Select a size that matches the hardware requirements(see {ref}`sec-minimum-hardware-requirements`). For example, select `Standard_D16ps_v5`, which has 16 vCPUs and 64 GB of RAM. * Change the user name of the administrator account to `ubuntu`. * Accept the defaults for the inbound port rules for now; these rules will be configured later in the setup process. @@ -101,15 +110,17 @@ To do so, go to the resource page of your virtual machine and find its public IP ssh -i Downloads/anbox-cloud-appliance_key.pem ubuntu@192.0.2.15 -## Finish the installation +### Finish the installation -Perform the following steps to finish the appliance installation on the virtual machine. If you are not already familiar with how to perform these steps, see the [tutorial on installing the appliance](https://discourse.ubuntu.com/t/22681) for detailed instructions. +Perform the following steps to finish the appliance installation on the virtual machine. If you are not already familiar with how to perform these steps, see {ref}`tut-installing-appliance` for detailed instructions. -1. Install the Anbox Cloud Appliance on the virtual machine. - [note type="information" status="Note"]Remember to attach the virtual machine to your Ubuntu Pro subscription, while installing the appliance. [/note] +1. Install the Anbox Cloud Appliance on the virtual machine. + ```{note} + Remember to attach the virtual machine to your Ubuntu Pro subscription, while installing the appliance. + ``` 1. Initialise the appliance. 1. Register your Ubuntu SSO account with the appliance dashboard. -[/details] +
When you are done, you can log into the appliance dashboard using `https://your-machine-address` with your Ubuntu SSO account. diff --git a/howto/install-appliance/google-cloud.md b/howto/install-appliance/google-cloud.md index 9cf25731..1d698baf 100644 --- a/howto/install-appliance/google-cloud.md +++ b/howto/install-appliance/google-cloud.md @@ -1,13 +1,18 @@ +(howto-install-appliance-google-cloud)= +# How to install the appliance on Google Cloud + The Anbox Cloud Appliance is not yet available from the Google Marketplace. However, you can install the Anbox Cloud Appliance snap on a Google Cloud instance by using this guide. The entire deployment process will take 20-30 minutes, depending on the selected hardware and the network conditions. -[note type="caution" status="Warning"]Currently, Anbox Cloud requires support for 32-bit architecture. Since T2A ARM instances are not available with 32-bit support, the T2A instance family on Google Cloud cannot be supported by Anbox Cloud. See [Google's documentation on T2A limitations](https://cloud.google.com/compute/docs/general-purpose-machines#t2a_limitations) for more information.[/note] +```{caution} +Currently, Anbox Cloud requires support for 32-bit architecture. Since T2A ARM instances are not available with 32-bit support, the T2A instance family on Google Cloud cannot be supported by Anbox Cloud. See [Google's documentation on T2A limitations](https://cloud.google.com/compute/docs/general-purpose-machines#t2a_limitations) for more information. +``` ## Prerequisites Before starting the procedure, -* Check the hardware requirements for the Anbox Cloud Appliance [here](https://discourse.ubuntu.com/t/17734). +* Check the hardware requirements listed in {ref}`ref-requirements` for the Anbox Cloud Appliance. * Make sure that you have a Google Cloud account and a project on Google Cloud to create the virtual machine. * If you wish to use your own [Ubuntu Pro subscription](https://ubuntu.com/pro), ensure you have the Ubuntu Pro token for your Ubuntu Pro subscription. If you wish to use the Ubuntu Pro subscription offered by Google Cloud along with the virtual machine, skip this prerequisite. @@ -34,9 +39,11 @@ Configure the boot disk by selecting **Boot disk > Change** to choose the operat ![Configure boot disk|690x440](https://assets.ubuntu.com/v1/884d0b10-boot-disk-config-2.png) -Select the operating system. Google Cloud has two options - Ubuntu and Ubuntu Pro. If you have an Ubuntu Pro subscription already, you can choose Ubuntu and [attach your subscription](https://discourse.ubuntu.com/t/install-the-anbox-cloud-appliance-on-a-dedicated-machine/22681#h-2-attach-your-machine-to-the-ubuntu-pro-subscription-4) manually. If you don’t, you can choose the Ubuntu Pro option which will include a Ubuntu Pro subscription through Google Cloud. +Select the operating system. Google Cloud has two options - Ubuntu and Ubuntu Pro. If you have an Ubuntu Pro subscription already, you can choose Ubuntu and attach your subscription(see {ref}`tut-installing-appliance`) manually. If you don’t, you can choose the Ubuntu Pro option which will include a Ubuntu Pro subscription through Google Cloud. -[note type="information" status="Note"]Remember that choosing the Ubuntu Pro option will impact your pricing. Google Cloud provides the resource details and associated costs in the **Pricing summary** section on the **Create an instance** page.[/note] +```{note} +Remember that choosing the Ubuntu Pro option will impact your pricing. Google Cloud provides the resource details and associated costs in the **Pricing summary** section on the **Create an instance** page. +``` Select the latest Ubuntu image for the architecture that you want to use. For example, Ubuntu 22.04 LTS Pro Server for Arm64. @@ -99,11 +106,14 @@ To complete the installation: 1. Install the Anbox Cloud Appliance on the virtual machine. - [note type="information" status="Note"]If you choose Ubuntu Pro as your operating system, you can ignore the step in the installation instructions that guides you to attach your machine to the Ubuntu Pro subscription as the subscription is included with the Google Cloud resources. You can check the status of the Ubuntu Pro subscription by running `pro status`.[/note] + ```{note} + If you choose Ubuntu Pro as your operating system, you can ignore the step in the installation instructions that guides you to attach your machine to the Ubuntu Pro subscription as the subscription is included with the Google Cloud resources. You can check the status of the Ubuntu Pro subscription by running `pro status`. + ``` 1. Initialise the appliance. 1. Register your Ubuntu SSO account with the appliance dashboard. -[note type="information" status="Note"]If you are not already familiar with how to perform these steps, see the [tutorial on installing the appliance](https://discourse.ubuntu.com/t/22681) for detailed instructions.[/note] +```{note} +If you are not already familiar with how to perform these steps, see {ref}`tut-installing-appliance` for detailed instructions.``` When you are done, you can log into the appliance dashboard using `https://your-machine-address` with your Ubuntu SSO account. diff --git a/howto/install-appliance/landing.md b/howto/install-appliance/landing.md index ebec7265..06a5aefc 100644 --- a/howto/install-appliance/landing.md +++ b/howto/install-appliance/landing.md @@ -1,20 +1,31 @@ +(howto-install-appliance)= +# How to install the Anbox Cloud Appliance + The Anbox Cloud Appliance provides a deployment of Anbox Cloud to a single machine. This offering is well suited for initial prototype and small scale deployments. -The guides in this section describe how to install the Anbox Cloud Appliance on different cloud platforms. There is a difference between the full Anbox Cloud installation and the Anbox Cloud Appliance (see [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1)). This section focuses on the **Anbox Cloud Appliance**. For instructions on how to install **Anbox Cloud**, see [How to install Anbox Cloud](https://discourse.ubuntu.com/t/install-anbox-cloud/24336). +The guides in this section describe how to install the Anbox Cloud Appliance on different cloud platforms. There is a difference between the full Anbox Cloud installation and the Anbox Cloud Appliance (see {ref}`sec-variants`). This section focuses on the **Anbox Cloud Appliance**. For instructions on how to install **Anbox Cloud**, see {ref}`howto-install-anbox-cloud`. -We strongly recommend that you follow the [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/install-appliance/22681) tutorial before you install the appliance on a cloud platform. The tutorial guides you through installing the appliance on a machine dedicated to Anbox Cloud and makes you familiar with the installation process and the general concepts of the Anbox Cloud Appliance. +We strongly recommend that you follow the {ref}`tut-installing-appliance` tutorial before you install the appliance on a cloud platform. The tutorial guides you through installing the appliance on a machine dedicated to Anbox Cloud and makes you familiar with the installation process and the general concepts of the Anbox Cloud Appliance. -Always check the [Requirements](https://discourse.ubuntu.com/t/installation-requirements/17734) before you start your installation. +Also, see {ref}`ref-requirements` before you start your installation. ## Supported cloud platforms The Anbox Cloud Appliance is currently available for the following cloud platforms: -* [AWS](https://discourse.ubuntu.com/t/how-to-install-the-appliance-on-aws/29703) +* {ref}`howto-install-appliance-aws` Other clouds are also supported, but the Anbox Cloud Appliance is not available from their application directories yet. Therefore, to install the appliance on such a cloud, install the Anbox Cloud Appliance snap on a cloud machine. See the following instructions: -* For [Azure](https://azure.microsoft.com/) : [How to install the appliance on Azure](https://discourse.ubuntu.com/t/how-to-install-the-appliance-on-azure/30824) -* For [Google Cloud](https://cloud.google.com/) : [How to install the appliance on Google Cloud](https://discourse.ubuntu.com/t/how-to-install-the-appliance-on-google-cloud/36254) +* For [Azure](https://azure.microsoft.com/) : {ref}`howto-install-appliance-azure` +* For [Google Cloud](https://cloud.google.com/) : {ref}`howto-install-appliance-google-cloud` + +For all other cloud platforms, follow the steps detailed in {ref}`tut-installing-appliance`. + +```{toctree} +:hidden: -For all other cloud platforms, follow the steps detailed in [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/install-appliance/22681) guide. +AWS +Azure +Google Cloud +``` diff --git a/howto/install/customise.md b/howto/install/customise.md index 8eb6a0b7..d57d52d1 100644 --- a/howto/install/customise.md +++ b/howto/install/customise.md @@ -1,3 +1,6 @@ +(howto-customise-installation)= +# How to customise your installation + There are two main ways to customise the Anbox Cloud deployment: 1. Use overlays in conjunction with the published Anbox Cloud bundle. @@ -9,7 +12,7 @@ Saving a copy of the bundle file and editing that file means that your customisa ## Use overlay files -An [overlay bundle](https://juju.is/docs/sdk/bundle-reference#heading--overlay-bundles) is a fragment of valid YAML that is dynamically merged on top of a bundle file before deployment, similar to a patch file. The fragment can contain additional or alternative YAML that is intelligible to Juju. For example, you could use a bundle overlay to specify custom instance types for the machines you use (note that the specified constraints are just an example and not a recommendation): +An [overlay bundle](https://juju.is/docs/juju/bundle) is a fragment of valid YAML that is dynamically merged on top of a bundle file before deployment, similar to a patch file. The fragment can contain additional or alternative YAML that is intelligible to Juju. For example, you could use a bundle overlay to specify custom instance types for the machines you use (note that the specified constraints are just an example and not a recommendation): machines: '0': @@ -77,7 +80,7 @@ This will give the same result as configuring the proxy values through Juju: Another way to change or customise a deployment is to store the YAML bundle file locally and edit it with a text editor. -The latest version of the Anbox Cloud bundles can be retrieved by fetching the current stable version from [Charmhub](https://charmhub.io/). See [Juju bundles](https://discourse.ubuntu.com/t/about-anbox-cloud/17802#juju-bundles-7) for more details on the available bundles. +The latest version of the Anbox Cloud bundles can be retrieved by fetching the current stable version from [Charmhub](https://charmhub.io/). See {ref}`sec-juju-bundles` for more details on the available bundles. Be careful when editing the YAML file, because the format is very strict. For more details on the format used by Juju, see the [Juju bundle documentation](https://juju.is/docs/sdk/bundle-reference). diff --git a/howto/install/deploy-bare-metal.md b/howto/install/deploy-bare-metal.md index f72aead6..8de02dae 100644 --- a/howto/install/deploy-bare-metal.md +++ b/howto/install/deploy-bare-metal.md @@ -1,4 +1,7 @@ -To deploy Anbox Cloud on a public cloud (such as AWS, Azure or Google) or using MAAS or OpenStack, see the instructions in [How to deploy Anbox Cloud with Juju](https://discourse.ubuntu.com/t/deploy-anbox-cloud-with-juju/17744). +(howto-deploy-anbox-baremetal)= +# How to deploy Anbox Cloud on bare metal + +To deploy Anbox Cloud on a public cloud (such as AWS, Azure or Google) or using MAAS or OpenStack, see the instructions in {ref}`howto-deploy-anbox-juju`. Alternatively, you can follow the instructions in this document to use the [manual cloud provider](https://jaas.ai/docs/manual-cloud) that Juju offers. This method allows you to deploy Anbox Cloud with Juju on a set of SSH connected machines. @@ -6,9 +9,11 @@ Alternatively, you can follow the instructions in this document to use the [manu Before you start the installation, ensure that you have the required prerequisites: -* At least three Ubuntu machines. See [Minimum hardware](https://discourse.ubuntu.com/t/requirements/17734#minimum-hardware-11) for details and recommendations. -* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to https://ubuntu.com/pro to retrieve it. - [note type="caution" status="Warning"]The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an *Ubuntu Pro* subscription.[/note] +* At least three Ubuntu machines. See {ref}`sec-minimum-hardware-requirements` for details and recommendations. +* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to [Ubuntu Pro](https://ubuntu.com/pro) to retrieve it. + ```{caution} + The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an *Ubuntu Pro* subscription. + ``` ## Install Juju @@ -18,7 +23,7 @@ You must install a Juju client on the machine that you use to run the deployment sudo snap install --classic --channel=2.9/stable juju -See [Juju version](https://discourse.ubuntu.com/t/installation-requirements/17734#juju-version-10) for information about which Juju version is required for your version of Anbox Cloud. +See {ref}`sec-juju-version-requirements` for information about which Juju version is required for your version of Anbox Cloud. ## Add a controller and model @@ -36,7 +41,7 @@ When the controller is set up, create a model to hold the Anbox Cloud deployment ## Add all machines -Before starting the deployment, you must add all machines to the Juju model. See [Minimum hardware](https://discourse.ubuntu.com/t/requirements/17734#minimum-hardware-11) for the list of machines that you need. +Before starting the deployment, you must add all machines to the Juju model. See {ref}`sec-minimum-hardware-requirements` for the list of machines that you need. When adding the machines, start with the machine that you want to host the management layer of Anbox Cloud. Then add all LXD worker nodes. Run the following command for each machine: @@ -44,7 +49,9 @@ When adding the machines, start with the machine that you want to host the manag The user (for example, `ubuntu`) must have administrator rights on the machine and have permission to SSH to the machine. -[note type="caution" status="Warning"]Make sure to add the machines by their IP addresses rather than their DNS names. Adding a machine by DNS name does currently not work.[/note] +```{caution} +Make sure to add the machines by their IP addresses rather than their DNS names. Adding a machine by DNS name does currently not work. +``` Juju will add the machines to its list of usable machines, which you can display with the `juju list-machines` command. Make sure that all machines are in the `started` state before you proceed. If any of the machines are still in `down` state, wait until they switch to `started`: @@ -54,13 +61,13 @@ Juju will add the machines to its list of usable machines, which you can display ## Attach your Ubuntu Pro subscription -Create an `ua.yaml` overlay file as described in [How to deploy Anbox Cloud with Juju](https://discourse.ubuntu.com/t/deploy-anbox-cloud-with-juju/17744#ua-overlay). +Create an `ua.yaml` overlay file as described in {ref}`sec-attach-pro-subscription`. You must provide this file when deploying Anbox Cloud. ## Determine the machine mapping -When running the deployment command, you must map the machines to the ones described in the [Juju bundle](https://discourse.ubuntu.com/t/about-anbox-cloud/17802#juju-bundles-7) that you are deploying. +When running the deployment command, you must map the machines to the ones described in {ref}`sec-juju-bundles` that you are deploying. Run `juju list-machines` to display the available machines: @@ -74,18 +81,17 @@ The `anbox-cloud` bundle requires two additional machines to host the load balan The `--map-machine` argument for the `juju deploy` command maps the machines defined inside the bundle to those your Juju controller has registered in the model. See the [Juju documentation](https://jaas.ai/docs/charm-bundles) for more details. If you added the machines in the order Juju expects them, the mapping is very straight-forward: `--map-machines 0=0,1=1` for the `anbox-cloud-core` bundle or `--map-machines 0=0,1=1,2=2,3=3` for the `anbox-cloud` bundle. - +(sec-customise-storage-bare-metal)= ## Customise storage -By default, Anbox Cloud uses a loop file with an automatically calculated size for LXD storage. For optimal performance, however, you should use a dedicated block storage device. See [LXD storage](https://discourse.ubuntu.com/t/anbox-cloud-overview/17802#lxd-storage-6) for more information. +By default, Anbox Cloud uses a loop file with an automatically calculated size for LXD storage. For optimal performance, however, you should use a dedicated block storage device. See {ref}`sec-lxd-storage` for more information. There are different ways of configuring a dedicated block storage device: -- Use an existing LXD storage pool (recommended - see [Existing storage pool](#existing-storage-pool) below) -- Use a dedicated storage device (see [Dedicated storage device](#dedicated-storage-device) below) -- Use a storage device defined by Juju (see the *Customise storage* section in [How to deploy Anbox Cloud with Juju](https://discourse.ubuntu.com/t/install-with-juju/17744#customise-storage) for instructions) +- Use an [existing LXD storage pool](#existing-storage-pool) (recommended) +- Use a [dedicated storage device](#dedicated-storage-device) +- Use a storage device defined by Juju (see {ref}`sec-customise-storage-juju` for instructions) - ### Existing storage pool To use an existing LXD storage pool, set the [`storage_pool`](https://charmhub.io/ams/configure#storage_pool) configuration on the AMS charm to the name of the LXD storage pool that you want Anbox Cloud to use. @@ -99,11 +105,10 @@ applications: storage_pool: my-zfs-pool ``` -[note type="information" status="Important"] +```{important} The LXD storage pool must use the ZFS storage driver. Other storage drivers are not supported by Anbox Cloud. -[/note] +``` - ### Dedicated storage device To use a dedicated storage device that is not defined by Juju for LXD storage, set the [`storage_device`](https://charmhub.io/ams/configure#storage_device) configuration on the AMS charm to the path of the storage device. @@ -117,9 +122,9 @@ applications: storage_device: /dev/sdb ``` -[note type="information" status="Important"] +```{important} The path to the dedicated storage device must be identical for all machines that are part of the cluster. -[/note] +``` You do not need to prepare the storage device in any way. AMS takes care of creating the LXD storage pool on the device. @@ -127,7 +132,7 @@ You do not need to prepare the storage device in any way. AMS takes care of crea Now you can deploy Anbox Cloud. The deployment is entirely handled by Juju and does not need any manual involvement other than running the actual deploy command. -Choose between the available [Juju bundles](https://discourse.ubuntu.com/t/about-anbox-cloud/17802#juju-bundles-7): +Choose between the available Juju bundles (see {ref}`sec-juju-bundles`): * For a minimised version of Anbox Cloud without the streaming stack, run the following command to deploy the `anbox-cloud-core` bundle: diff --git a/howto/install/deploy-juju.md b/howto/install/deploy-juju.md index c3dc4ee2..2f947413 100644 --- a/howto/install/deploy-juju.md +++ b/howto/install/deploy-juju.md @@ -1,10 +1,13 @@ +(howto-deploy-anbox-juju)= +# How to deploy Anbox Cloud with Juju + Anbox Cloud supports various public clouds, such as AWS, Azure and Google. To deploy Anbox Cloud in a cloud environment, you use Juju. -See the following sections for detailed instructions. If you want to install Anbox Cloud on bare metal instead of a public cloud, see [How to deploy Anbox Cloud on bare metal](https://discourse.ubuntu.com/t/deploy-anbox-cloud-on-bare-metal/26378) instead. +See the following sections for detailed instructions. If you want to install Anbox Cloud on bare metal instead of a public cloud, see {ref}`howto-deploy-anbox-baremetal` instead. -[note type="information" status="Note"] -There are differences between the full Anbox Cloud installation and the Anbox Cloud Appliance (see [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1)). This section focuses on **Anbox Cloud**. For instructions on how to install the **Anbox Cloud Appliance**, see [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702) or the [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/install-appliance/22681) tutorial. -[/note] +```{note} +There are differences between the full Anbox Cloud installation and the Anbox Cloud Appliance (see {ref}`sec-variants`). This section focuses on **Anbox Cloud**. For instructions on how to install the **Anbox Cloud Appliance**, see {ref}`tut-installing-appliance`. +``` ## Prerequisites @@ -15,8 +18,10 @@ Before you start the installation, ensure that you have the required credentials * [Amazon Web Services](https://aws.amazon.com/) (including AWS-China) * [Google Cloud platform ](https://cloud.google.com/) * [Microsoft Azure](https://azure.microsoft.com/) -* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to https://ubuntu.com/pro to retrieve it. - [note type="caution" status="Warning"]The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an Ubuntu Pro subscription.[/note] +* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to [Ubuntu Pro website](https://ubuntu.com/pro) to retrieve it. + ```{caution} + The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an Ubuntu Pro subscription. + ``` ## Install Juju @@ -26,7 +31,7 @@ To install Juju 2.9, enter the following command: sudo snap install --classic --channel=2.9/stable juju -See [Juju version](https://discourse.ubuntu.com/t/installation-requirements/17734#juju-version-10) for information about which Juju version is required for your version of Anbox Cloud. +See {ref}`sec-juju-version-requirements` for information about which Juju version is required for your version of Anbox Cloud. ## Authenticate with your cloud @@ -54,16 +59,18 @@ A Juju model holds a specific deployment. It is a good idea to create a new one You can have multiple models on each controller, which means that you can deploy multiple versions of Anbox Cloud, or other applications. - +(sec-attach-pro-subscription)= ## Attach your Ubuntu Pro subscription Every deployment of Anbox Cloud must be attached to the Ubuntu Pro service Canonical provides. This provides your deployment with the correct licences you're granted as part of your licence agreement with Canonical, next to other services available through your subscription like [Livepatch](https://ubuntu.com/livepatch). -You can retrieve your Ubuntu Pro token at https://ubuntu.com/pro after logging in. You should record the token as you will need it for every deployment of Anbox Cloud. +You can retrieve your Ubuntu Pro token at [`https://ubuntu.com/pro`](https://ubuntu.com/pro) after logging in. You should record the token as you will need it for every deployment of Anbox Cloud. -[note type="caution" status="Warning"]The *Ubuntu Pro (Infra-only)* token will result in a failed deployment. You need an *Ubuntu Pro* subscription.[/note] +```{caution} +The *Ubuntu Pro (Infra-only)* token will result in a failed deployment. You need an *Ubuntu Pro* subscription. +``` -To provide your token when deploying with Juju, you need an [overlay file](https://discourse.ubuntu.com/t/installation-customizing/17747#use-overlay-files-1) named `ua.yaml`. For the `anbox-cloud` bundle, the `ua.yaml` file should look like this: +To provide your token when deploying with Juju, you need an overlay file (see {ref}`howto-customise-installation`) named `ua.yaml`. For the `anbox-cloud` bundle, the `ua.yaml` file should look like this: ```yaml applications: @@ -103,18 +110,19 @@ applications: ``` You will use the overlay file during the deployment. - + +(sec-deploy-anbox-cloud-juju)= ## Deploy Anbox Cloud -[note type="information" status="Note"] +```{note} This section explains how to start the Anbox Cloud deployment without any customisation. However, in most cases you will want to include a custom configuration when you start the deployment. Therefore, make sure to check the following sections before you run the deploy command. -[/note] +``` To install Anbox Cloud, deploy the suitable Anbox Cloud bundle to the Juju model. This will add instances to the model and deploy the required applications. -Choose between the available [Juju bundles](https://discourse.ubuntu.com/t/about-anbox-cloud/17802#juju-bundles-7): +Choose between the available {ref}`sec-juju-bundles`: * For a minimised version of Anbox Cloud without the streaming stack, run the following command to deploy the `anbox-cloud-core` bundle: @@ -126,7 +134,7 @@ Choose between the available [Juju bundles](https://discourse.ubuntu.com/t/about ## Customise the hardware configuration -To customise the machine configuration Juju will use for the deployment, create another [overlay file](https://discourse.ubuntu.com/t/installation-customizing/17747#use-overlay-files-1). Here you can, for example, specify AWS instance types, change the size or source of the root disk or other things. See the [complete list of constraints](https://juju.is/docs/olm/constraint#heading--complete-list-of-constraints) in the Juju documentation for details. +To customise the machine configuration Juju will use for the deployment, create another overlay file. Here you can, for example, specify AWS instance types, change the size or source of the root disk or other things. See the [complete list of constraints](https://juju.is/docs/juju/constraint#heading--list-of-constraints) in the Juju documentation for details. For the `anbox-cloud-core` bundle, such an `overlay.yaml` file looks like this: @@ -162,10 +170,10 @@ To deploy, add `--overlay overlay.yaml` to your deploy command. For example: juju deploy anbox-cloud --overlay ua.yaml --overlay overlay.yaml - +(sec-customise-storage-juju)= ### Customise storage -By default, Anbox Cloud uses a loop file with an automatically calculated size for LXD storage. For optimal performance, however, you should use a dedicated block storage device. See [LXD storage](https://discourse.ubuntu.com/t/anbox-cloud-overview/17802#lxd-storage-6) for more information. +By default, Anbox Cloud uses a loop file with an automatically calculated size for LXD storage. For optimal performance, however, you should use a dedicated block storage device. See {ref}`sec-lxd-storage` for more information. The easiest way to do this is to use a storage device defined by Juju: @@ -189,9 +197,9 @@ The easiest way to do this is to use a storage device defined by Juju: pool: ebs-ssd,100GB,1 ``` - [note type="information" status="Note"] + ```{note} You can add only one storage pool. - [/note] + ``` When you deploy Anbox Cloud with this configuration, Juju allocates the requested storage and attaches it to LXD. During initialisation, AMS then configures LXD to create a ZFS storage pool on the configured storage. diff --git a/howto/install/high-availability.md b/howto/install/high-availability.md index c0736fb5..03fc0a6d 100644 --- a/howto/install/high-availability.md +++ b/howto/install/high-availability.md @@ -1,7 +1,10 @@ +(howto-enable-ha)= +# How to enable High Availability + Anbox Cloud comes with support for High Availability (HA) for both Core and the Streaming Stack. -Next to [Juju's support for high availability of the Juju controller](https://juju.is/docs/controller-high-availability), you can add HA for the [Anbox Management Service (AMS)](https://discourse.ubuntu.com/t/about-ams/24321) and the Anbox Stream Gateway to ensure fault tolerance and higher uptime. +In addition to Juju's support for high availability of the Juju controller( see [Juju documentation](https://juju.is/docs/juju/manage-controllers#heading--make-a-controller-highly-available)), you can add HA for the Anbox Management Service (AMS) and the Anbox Stream Gateway to ensure fault tolerance and higher uptime. -Enabling High Availability (HA for short) is achieved by [adding new units via Juju](https://juju.is/docs/olm/manage-applications#heading--scale-an-application). +Enabling High Availability (HA for short) is achieved by adding new units via Juju(see [Juju documentation](https://juju.is/docs/olm/manage-applications#heading--scale-an-application)). This will allocate a new machine, run new instances of the scaled application and configure the cluster automatically. Adding a unit is done with the following syntax: @@ -12,13 +15,13 @@ For example, to go from 1 to 5 AMS units, you would run the following: juju add-unit ams -n 4 -[note type="information" status="Tip"] +```{tip} By default, Juju allocates small machines to limit costs but you can request better resources by [enforcing constraints](https://juju.is/docs/olm/constraints): `juju set-constraints anbox-stream-gateway cores=4 memory=8GB` This is heavily recommended on production environments. -[/note] +``` ## Anbox Cloud Core @@ -78,7 +81,7 @@ anbox-stream-gateway/2 active idle 4 10.212.218.136 4000/tcp,70 ## Scaling down -Scaling down can be done by [removing units via Juju](https://juju.is/docs/olm/manage-applications#heading--scale-an-application). You have to specifically target the unit that you want to remove: +Scaling down can be done by removing units via Juju (see [Juju documentation](https://juju.is/docs/olm/manage-applications#heading--scale-an-application)). You have to specifically target the unit that you want to remove: juju remove-unit anbox-stream-agent/2 diff --git a/howto/install/landing.md b/howto/install/landing.md index 1737ad16..5d20ed7d 100644 --- a/howto/install/landing.md +++ b/howto/install/landing.md @@ -1,5 +1,18 @@ -The guides in this section describe how to install Anbox Cloud. +(howto-install-anbox-cloud)= +# How to install Anbox Cloud -It is important to remember that there is a difference between the full Anbox Cloud installation and the Anbox Cloud Appliance (see [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1)). This section focuses on **Anbox Cloud**. For instructions on how to install the **Anbox Cloud Appliance**, see [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702) or the [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/install-appliance/22681) tutorial. +It is important to remember that there is a difference between the full Anbox Cloud installation and the Anbox Cloud Appliance (see {ref}`sec-variants`). This section focuses on **Anbox Cloud**. For instructions on how to install the **Anbox Cloud Appliance**, see {ref}`tut-installing-appliance`. -Also, check the [Requirements](https://discourse.ubuntu.com/t/installation-requirements/17734) before you start your installation. +Also, see {ref}`ref-requirements` before you start your installation. + +The following guides in this section describe how to install Anbox Cloud. + +```{toctree} +:titlesonly: + +Customise your installation +Deploy on bare metal +Deploy with Juju +Enable high availability +Validate deployment +``` diff --git a/howto/install/validate.md b/howto/install/validate.md index ab1a2afb..f6c7bc50 100644 --- a/howto/install/validate.md +++ b/howto/install/validate.md @@ -1,3 +1,6 @@ +(howto-validate-deployment)= +# How to validate the deployment + Anbox Cloud includes a test suite which allows the validation of an Anbox Cloud deployment. It comes with various tests covering different features of Anbox Cloud and can be used to ensure everything works as expected. The validation tests currently cover the following areas of an Anbox Cloud deployment: @@ -85,11 +88,11 @@ suites: gpu-type: none ``` -As mentioned by the command you have to store the printed configuration to a file so it can be used by the tests later on. Also you need to register the generated TLS certificate for the AMS tests with AMS. See [How to control AMS remotely](https://discourse.ubuntu.com/t/managing-ams-access/17774) for more details on how to do that. +As mentioned by the command you have to store the printed configuration to a file so it can be used by the tests later on. Also you need to register the generated TLS certificate for the AMS tests with AMS. See {ref}`howto-access-ams-remote` for more details on how to do that. Depending on your deployment you can further customise the generated configuration. For example may your deployment only support a single architecture for the instances. For that make sure the `suites.ams.supported-architectures` field is set to the right list of architectures. -If you have support for real GPUs set the `suites.ams.gpu-type` item to the right GPU type (supported values are: `nvidia`, `amd`, `intel`, `none`) and add GPU based instance types (see [Instance types](https://discourse.ubuntu.com/t/application-manifest/24197#instance-type-1) for more details) to the `suites.ams.instance-types`. +If you have support for real GPUs, set the `suites.ams.gpu-type` item to the right GPU type (supported values are: `nvidia`, `amd`, `intel`, `none`) and add GPU based instance types (see {ref}`sec-application-manifest-instance-type` for more details) to the `suites.ams.instance-types`. ## Run the Validation Tests diff --git a/howto/instance/access.md b/howto/instance/access.md index 759152ed..f19cf320 100644 --- a/howto/instance/access.md +++ b/howto/instance/access.md @@ -1,3 +1,6 @@ +(howto-access-instance)= +# How to access an instance + In some cases, it might be necessary to access an individual instance for debugging reasons. You can do this on the command line with the `amc` command, or you can use [scrcpy](https://github.com/Genymobile/scrcpy) for graphical access. @@ -18,6 +21,7 @@ If you only want to watch the Android log output, use the following command: `amc shell` and `amc exec` open various possibilities for automation use cases. See the help output of the commands for further details. +(sec-access-instance-scrcpy)= ## Access an instance with scrcpy The AMS services enable connecting remotely over a network to instance via [scrcpy](https://github.com/Genymobile/scrcpy). @@ -35,14 +39,18 @@ Install scrcpy in one of the following ways: apt install scrcpy + ```{note} - [note type="information" status="Note"]The packaged version from the Ubuntu repositories may not be the latest. It is recommended to follow the instructions mentioned in the [scrcpy documentation](https://github.com/Genymobile/scrcpy/blob/master/doc/linux.md#latest-version) to install the latest version of scrcpy.[/note] + The packaged version from the Ubuntu repositories may not be the latest. It is recommended to follow the instructions mentioned in the [scrcpy documentation](https://github.com/Genymobile/scrcpy/blob/master/doc/linux.md#latest-version) to install the latest version of scrcpy. + ``` * Install scrcpy from the [Ubuntu snap store](https://snapcraft.io): sudo snap install scrcpy - [note type="information" status="Note"]The scrcpy snap package that is published to snap store is a non-official package. You can use it, but it's at your own risk. Because of this, it's highly recommended to build scrcpy from source by yourself.[/note] + ```{note} + The scrcpy snap package that is published to snap store is a non-official package. You can use it, but it's at your own risk. Because of this, it's highly recommended to build scrcpy from source by yourself. + ``` ### Launch instance @@ -50,7 +58,9 @@ First, launch an instance with graphics enabled: amc launch -s +adb --enable-graphics -r default -[note type="information" status="Note"]Use the `--vm` flag to launch a virtual machine.[/note] +```{note} +Use the `--vm` flag to launch a virtual machine. +``` The above command will launch a container instance from the default image. Since scrcpy requires ADB to establish the connection between your host and the instance, the ADB service must be enabled by default. With the leading `+` symbol to the `adb` service, it exposes TCP port 5559 on the public address of the node. @@ -66,7 +76,9 @@ Afterwards you can find the network endpoint of the instance in the output of th The endpoint of the ADB service exposed from the running instance is available at 10.226.4.200:10000 on the public network. -[note type="caution" status="Warning"]Exposing the ADB service over the public internet brings security risks from having plain text data intercepted by third parties. It's always preferable to run scrcpy [through an encrypted SSH tunnel](#through-ssh-tunnel-6) if possible.[/note] +```{caution} +Exposing the ADB service over the public internet brings security risks from having plain text data intercepted by third parties. It's always preferable to run scrcpy [through an encrypted SSH tunnel](#through-ssh-tunnel) if possible. +``` ### Run scrcpy @@ -92,7 +104,9 @@ To set up a secure connection, launch the instance so that it doesn't expose the amc launch -s adb --enable-graphics -r default -[note type="information" status="Note"]Use the `--vm` flag to launch a virtual machine.[/note] +```{note} +Use the `--vm` flag to launch a virtual machine. +``` As the ADB service is enabled for the launched instance but without the leading `+`, the endpoint `10.226.4.168:10000/tcp` shown via `amc ls` is not exposed to the public network: diff --git a/howto/instance/backup-and-restore.md b/howto/instance/backup-and-restore.md index 3ccb49d1..49fdeffe 100644 --- a/howto/instance/backup-and-restore.md +++ b/howto/instance/backup-and-restore.md @@ -1,3 +1,6 @@ +(howto-backup-restore-application-data)= +# How to back up and restore application data + Backup and restoration of application data can be achieved easily with the `aam` (Anbox Application Manager) utility helper installed in the image. The `aam` can bundle any necessary application data together into a tarball file or extract the tarball file to a particular application folder according to the specified package name. ## Back up application data @@ -11,9 +14,9 @@ TARBALL_FILE=$(basename $(find ./ -name *.tar.bz2)) # Upload the tarball to public or private cloud storage service curl -i -X POST --data-binary @"${TARBALL_FILE}" ``` -Running this script in an [addon post-stop hook](https://discourse.ubuntu.com/t/example-back-up-data/25289) will back up the user data of a particular application with `aam` and upload the resulting tarball file to the cloud storage service when an instance is stopped. +Running this script in an addon post-stop hook will back up the user data of a particular application with `aam` and upload the resulting tarball file to the cloud storage service when an instance is stopped. -If [`boot-package`](https://discourse.ubuntu.com/t/application-manifest/24197) is specified in the application manifest file, you can also back up the boot application data simply with the flag `--boot-package`. +If `boot-package` is specified in the application manifest file, you can also back up the boot application data simply with the flag `--boot-package`. aam backup --boot-package @@ -22,7 +25,7 @@ If [`boot-package`](https://discourse.ubuntu.com/t/application-manifest/24197) i ## Restore application data -The application data can be restored with the following [pre-start hook](https://discourse.ubuntu.com/t/example-back-up-data/25289#restore-data-2) when an instance is up and running: +The application data can be restored with the following pre-start hook when an instance is up and running: ```bash #!/bin/sh -ex @@ -45,7 +48,7 @@ Sometimes, not every piece of data is useful (for example, cache), and backing u `include` | Include files in resulting tarball with a wildcard `exclude` | Exclude files in resulting tarball with a wildcard -Please refer to the pattern syntax [here](https://golang.org/pkg/path/filepath/#Match). +Please refer to the pattern syntax [in the Go documentation](https://golang.org/pkg/path/filepath/#Match). For example, with the following filters: @@ -66,3 +69,7 @@ And exclude the following files: * Files with `jpeg` suffix below the folder `/sdcard/Android/data/com.canonical.candy/user_data` * Files with `cfg` suffix below the folder `/data/data/com.canonical.candy/new_level` + +## Related topics + +* {ref}`howto-backup-restore-example` \ No newline at end of file diff --git a/howto/instance/create.md b/howto/instance/create.md index 10bec734..5e2a6be8 100644 --- a/howto/instance/create.md +++ b/howto/instance/create.md @@ -1,3 +1,5 @@ +(howto-create-instance)= +# How to create an instance To launch an application or an image, Anbox Cloud creates an instance for it. To create and launch an instance, you can use the Anbox Cloud dashboard or the CLI. ## Using the dashboard @@ -23,6 +25,7 @@ By default, the instance will run headless. The following examples demonstrate different ways of launching instances using `amc launch`, but you can use `amc init` in the same way. +(sec-launch-application-instances)= ### Launch application instances Before launching an instance for an application, get the ID of the application that for which you want to launch an instance. To do this, run: @@ -39,11 +42,14 @@ This command lists the available applications along their IDs and their publishe +----------------------+----------------+---------------+--------+-----------+--------+---------------------+ ``` -To launch an instance for a [published](https://discourse.ubuntu.com/t/how-to-update-an-application/24201#publish-application-versions-1) application, run: +To launch an instance for a published application, run: amc launch -[note type="information" Status="Tip"]The `--vm` flag is not required when you specify an application id. The application has the information about whether a container or a virtual machine is to be created.[/note] +```{tip} +- To know about published applications, see {ref}`sec-publish-app-versions`. +- The `--vm` flag is not required when you specify an application id. The application has the information about whether a container or a virtual machine is to be created. +``` The `amc launch` command fails if you provide the ID of an application that is not yet published. However, if you have a specific version of an application that has been published, you can specify it to launch the instance successfully: @@ -51,8 +57,11 @@ The `amc launch` command fails if you provide the ID of an application that is n ### Launch a raw instance -You can launch a [raw instance](https://discourse.ubuntu.com/t/instances/17763#application-instances-vs-raw-instances-2) from an image. To do so, get the ID of the image by running: +You can launch a raw instance from an image. To do so, get the ID of the image by running: +```{tip} +If you don't know what a raw instance is, see {ref}`sec-application-raw-instances`. +``` amc image ls This command lists the available images along with their IDs and status: @@ -69,7 +78,7 @@ Launch a raw instance by providing the image ID in the following command: amc launch --raw -See [Provided images](https://discourse.ubuntu.com/t/provided-images/24185) for a list of images that are available in Anbox Cloud. +See {ref}`ref-provided-images` for a list of images that are available in Anbox Cloud. ### Launch an instance with streaming enabled @@ -107,7 +116,9 @@ By default, every instance is scheduled by AMS onto a LXD node. Alternatively, y amc launch --node=lxd0 -[note type="information" status="Note"]AMS will still verify that the selected node has enough resources to host the instance. If not, the instance will fail to launch.[/note] +```{note} +AMS will still verify that the selected node has enough resources to host the instance. If not, the instance will fail to launch. +``` ### Launch an instance with a different Anbox platform @@ -119,7 +130,7 @@ If you have built your own platform named `foo` and you built it via an addon in amc launch -p foo -For more information, see [supported platforms](https://discourse.ubuntu.com/t/supported-rendering-resources/37322#supported-platforms-3) and [configuration for supported platforms](https://discourse.ubuntu.com/t/configuration-for-supported-platforms/18733). +For more information, see {ref}`exp-platforms` and {ref}`sec-supported-platforms`. ### Launch an instance with development mode enabled @@ -129,8 +140,8 @@ To launch an instance with development mode enabled, add the `--devmode` flag to amc launch --devmode -## Related information +## Related topics -* [Instances](https://discourse.ubuntu.com/t/instances/17763) -* [How to access an instance](https://discourse.ubuntu.com/t/17772) -* [Application streaming](https://discourse.ubuntu.com/t/streaming-android-applications/17769) +* {ref}`exp-application-streaming` +* {ref}`exp-instances` +* {ref}`howto-access-instance` diff --git a/howto/instance/delete.md b/howto/instance/delete.md index 7f694978..70fd9b2c 100644 --- a/howto/instance/delete.md +++ b/howto/instance/delete.md @@ -1,3 +1,6 @@ +(howto-delete-instance)= +# How to delete an instance + An instance can be deleted, which will cause any connected user to be disconnected immediately. The following command deletes a single instance: amc delete diff --git a/howto/instance/expose-services.md b/howto/instance/expose-services.md index 269f8d76..1e50d307 100644 --- a/howto/instance/expose-services.md +++ b/howto/instance/expose-services.md @@ -1,8 +1,13 @@ +(howto-expose-services)= +# How to expose services on an instance + AMS allows an instance to expose a service to the outer network. For that, it provides a feature called instance services which let you define a port to expose on the instance endpoints. The set of services to expose is defined when the instance is launched. For example, the following command exposes port `22` on the instance's private endpoint: amc launch -s tcp:22 bdp7kmahmss3p9i8huu0 -[note type="information" status="Note"]The specified port is exposed only on the IP address assigned to the instance. As the instance is normally not accessible from outside, the LXD node it is running on AMS sets up port forwarding rules on the node and maps the specified port to one in a higher port range (`10000 - 110000`).[/note] +```{note} +The specified port is exposed only on the IP address assigned to the instance. As the instance is normally not accessible from outside, the LXD node it is running on AMS sets up port forwarding rules on the node and maps the specified port to one in a higher port range (`10000 - 110000`). +``` The list of instances (`amc ls`) will now show the instance and the exposed port `22`: diff --git a/howto/instance/geographic-location.md b/howto/instance/geographic-location.md index 2c3a0d10..585dd5f1 100644 --- a/howto/instance/geographic-location.md +++ b/howto/instance/geographic-location.md @@ -1,3 +1,6 @@ +(howto-configure-geographic-location)= +# How to configure geographic location + Anbox Cloud allows specifying a geographic location for an Android container. This location can either be specified statically through a configuration file or dynamically through the HTTP API. ## Set a static location @@ -23,10 +26,13 @@ Latitude in hemisphere | char | Latitude hemisphere `N` (northern hemisph Longitude | float | In the format of `ddmm.mm` (d refers to degrees, m refers to minutes). For example: 1131.001 = 11 degrees 31.001 minutes Longitude in hemisphere | char | hemisphere `E` (east longitude) or `W` (west longitude) -To make the file `/var/lib/anbox/static_gps_position` available to the Android container, create a file that contains GPS data in the above format and move that file from `ADDON_DIR` to `/var/lib/anbox/static_gps_position` via an [addon pre-start hook](https://discourse.ubuntu.com/t/managing-addons/17759) during the installation. When an Android container gets started and an application requests the current location information through the Android framework, the GPS data is then forwarded from the Anbox session to the application. +To make the file `/var/lib/anbox/static_gps_position` available to the Android container, create a file that contains GPS data in the above format and move that file from `ADDON_DIR` to `/var/lib/anbox/static_gps_position` via an addon pre-start hook during the installation. When an Android container gets started and an application requests the current location information through the Android framework, the GPS data is then forwarded from the Anbox session to the application. ## Set the location dynamically To update the geographic location of an Android container dynamically while the instance is running, use the location endpoint of the Anbox HTTP API. -See the documentation of the [PATCH method](https://discourse.ubuntu.com/t/anbox-http-api-reference/17819#location-patch) for more information and the specification of the data format. +See {ref}`sec-anbox-https-api-location` for information on the PATCH method and the specification of the data format. + +## Related topics +* {ref}`howto-addons` diff --git a/howto/instance/landing.md b/howto/instance/landing.md index 7be92360..206d9b88 100644 --- a/howto/instance/landing.md +++ b/howto/instance/landing.md @@ -1,3 +1,21 @@ -The guides in this section describe how to work with instances in Anbox Cloud. +(howto-instance)= +# How to manage instances -See [About instances](https://discourse.ubuntu.com/t/17763) for an introduction to how instances are used in Anbox Cloud. +The following guides in this section describe how to work with instances in Anbox Cloud. + +```{toctree} +:titlesonly: + +Access an instance +Backup and restore data +Create an instance +Delete an instance +Expose services on an instance +Configure geographic location +List instances +View instance logs +Start an instance +Stop an instance +Wait for an instance +``` +See {ref}`exp-instances` for an introduction to how instances are used in Anbox Cloud. diff --git a/howto/instance/list.md b/howto/instance/list.md index b2a98f77..5a361f10 100644 --- a/howto/instance/list.md +++ b/howto/instance/list.md @@ -1,3 +1,6 @@ +(howto-list-instances)= +# How to list instances + To get an overview of the running status of instances on an Anbox Cloud deployment, run the `amc ls` command: ```bash diff --git a/howto/instance/logs.md b/howto/instance/logs.md index 5abfca0f..ec356589 100644 --- a/howto/instance/logs.md +++ b/howto/instance/logs.md @@ -1,5 +1,10 @@ +(howto-view-instance-logs)= +# How to view the instance logs + You can view the Anbox and the Android system logs while an instance is running, or check the collected logs if an instance fails. -[note type="information" status="Note"]AMS does not support runtime log collection. Logs are currently only being collected from an instance that failed to start or had an error at runtime.[/note] +```{note} +AMS does not support runtime log collection. Logs are currently only being collected from an instance that failed to start or had an error at runtime. +``` ## View runtime logs @@ -15,6 +20,7 @@ To follow the log and get automatic updates for new entries, add the `-f` argume This will show the logs and update the output whenever new entries are added. +(sec-view-stored-logs)= ## View stored logs If an instance fails to start or a runtime error occurs, AMS collects relevant log files from the instance and makes them available for inspection. diff --git a/howto/instance/start.md b/howto/instance/start.md index 3471001b..98b0a659 100644 --- a/howto/instance/start.md +++ b/howto/instance/start.md @@ -1,12 +1,15 @@ -When an instance is either initialised with the `amc init` (see [Create an instance](https://discourse.ubuntu.com/t/24327)) command or stopped with the `amc stop` command (See [Stop an instance](https://discourse.ubuntu.com/t/33925)), you must start it explicitly with the `amc start` command: +(howto-start-instance)= +# How to start an instance + +When an instance is either initialised with the `amc init` command or stopped with the `amc stop` command, you must start it explicitly with the `amc start` command: amc start `` is the ID of the instance that you want to start. -[note type="information" status="Important"] +```{important} Do not use the `lxc` command to manage an instance. Always use the `amc` command instead. In Anbox Cloud, instances have their own life cycle and using the `lxc` command to manage an instance can cause the instance to be out of sync. -[/note] +``` By default, the `amc start` command waits 5 minutes for an instance to run before the operation times out. When starting an instance, you can specify a custom wait time with the `--timeout` option. @@ -16,6 +19,10 @@ When the `--no-wait` option is specified, the `amc start` command exits immediat amc start --no-wait -[note type="information" status="Important"] +```{important} Starting an instance that has stopped with an error status is is not allowed. Doing so would cause the `amc start` command to fail. -[/note] +``` + +## Related topics +* {ref}`howto-create-instance` +* {ref}`howto-stop-instance` diff --git a/howto/instance/stop.md b/howto/instance/stop.md index 46bd45b3..dc2cdf3c 100644 --- a/howto/instance/stop.md +++ b/howto/instance/stop.md @@ -1,12 +1,15 @@ +(howto-stop-instance)= +# How to stop an instance + A running instance can be stopped using the `amc stop` command: amc stop `` is the ID of the instance that you want to stop. -[note type="information" status="Important"] +```{important} Do not use the `lxc` command to manage an instance. Always use the `amc` command instead. In Anbox Cloud, instances have their own life cycle and using the `lxc` command to manage an instance can cause the instance to be out of sync. -[/note] +``` By default, the `amc stop` command waits 5 minutes for an instance to stop before the operation times out. If you want to specify a custom wait time, you can do so by using the `--timeout` option in the `amc stop` command. diff --git a/howto/instance/wait.md b/howto/instance/wait.md index 4007a5ed..d3165e35 100644 --- a/howto/instance/wait.md +++ b/howto/instance/wait.md @@ -1,3 +1,6 @@ +(howto-wait-for-instance)= +# How to wait for an instance + When launching an instance, the instance should not be considered started until it reaches the running state. Sometimes if you want to interact with the instance (with the `amc shell` command, for example), you must wait until the instance reaches a `running` status. The `amc wait` command allows to wait for an instance to reach a specific condition. If the condition is not satisfied within the specified time (five minutes by default), a timeout error will be returned by AMS. diff --git a/howto/landing.md b/howto/landing.md index 3a343106..48951a6e 100644 --- a/howto/landing.md +++ b/howto/landing.md @@ -1,41 +1,66 @@ +(how-to-guides)= +# How-to guides + The *How-to* guides in this section give directions on how to achieve your goals when configuring, managing or using Anbox Cloud. These *How-to* guides are more useful when you are familiar with Anbox Cloud and seek to achieve specific tasks. They help you complete your tasks but may require you to understand and adapt the steps to fit your specific requirements. ## Installing and configuring Anbox Cloud Learn how to install, configure and update Anbox Cloud. -* [Install and configure Anbox Cloud](https://discourse.ubuntu.com/t/24336) -* [Install and configure the Anbox Cloud Appliance on a cloud platform](https://discourse.ubuntu.com/t/29702) -* [Update your installation](https://discourse.ubuntu.com/t/24331) +* {ref}`howto-install-anbox-cloud` +* {ref}`howto-install-appliance` +* {ref}`howto-update` ## Using Anbox Cloud Learn about applications, instances and more in Anbox Cloud and how to use them. -* [Port Android apps](https://discourse.ubuntu.com/t/17776) -* [Manage applications and the Anbox Application Registry(AAR)](https://discourse.ubuntu.com/t/24333) -* [Manage, configure and work with instances](https://discourse.ubuntu.com/t/24335) -* [Use addons](https://discourse.ubuntu.com/t/17759) -* [Implement streaming for your application](https://discourse.ubuntu.com/t/implement-streaming/24332) +* {ref}`howto-port-android-apps` +* {ref}`howto-manage-applications` +* {ref}`howto-instance` +* {ref}`howto-addons` +* {ref}`howto-streaming` ## Managing Anbox Cloud Learn how to manage the different variants of Anbox Cloud, distribute the load of Anbox Cloud over several machines in a cluster and work with Anbox runtime. -* [Manage Anbox Cloud](https://discourse.ubuntu.com/t/24337) -* [Manage cluster nodes](https://discourse.ubuntu.com/t/24334) -* [Work with the Anbox runtime](https://discourse.ubuntu.com/t/33098) +* {ref}`howto-manage-anbox` +* {ref}`howto-manage-cluster` +* {ref}`howto-anbox-runtime` ## Monitoring Anbox Cloud Understand monitoring options for Anbox Cloud to further optimise your deployment. -* [Monitor Anbox Cloud](https://discourse.ubuntu.com/t/24338) +* {ref}`howto-monitor-anbox` ## Troubleshooting Anbox Cloud Learn resolutions for common issues with Anbox Cloud and how to collect useful debugging information before reporting an issue. -* [Troubleshoot Anbox Cloud](https://discourse.ubuntu.com/t/17837) - -Also check out the [Tutorials](https://discourse.ubuntu.com/t/tutorials/28826) for step-by-step instructions that help you get started with Anbox Cloud, as well as the [Reference](https://discourse.ubuntu.com/t/reference/28828) and [Explanation](https://discourse.ubuntu.com/t/explanation/28829) sections for other helpful information. +* {ref}`howto-ts-anbox-cloud` + +Also check out the {ref}`tutorials` for step-by-step instructions that help you get started with Anbox Cloud, as well as the {ref}`reference` and {ref}`explanation` sections for other helpful information. + + +```{toctree} +:hidden: + +Implement streaming +Install Anbox Cloud Appliance +Install Anbox Cloud (regular) +Manage AAR +Manage Addons +Manage Anbox Cloud +Manage Applications +Manage cluster nodes +Manage Instances +Monitor Anbox Cloud +Port Android apps +Troubleshoot Anbox Cloud +Update Anbox Cloud +Use web dashboard +Work with Anbox runtime +Work with Android +``` \ No newline at end of file diff --git a/howto/manage/landing.md b/howto/manage/landing.md deleted file mode 100644 index a3edc004..00000000 --- a/howto/manage/landing.md +++ /dev/null @@ -1,11 +0,0 @@ -The guides in this section help you to manage and work with your Anbox Cloud or Anbox Cloud Appliance installation. - -* [Set up TLS for the appliance](https://discourse.ubuntu.com/t/28552) -* [Manage Anbox Cloud images](https://discourse.ubuntu.com/t/17758) -* [Control AMS remotely](https://discourse.ubuntu.com/t/17774) -* [Run benchmarks](https://discourse.ubuntu.com/t/17770) -* [Resize LXD storage](https://discourse.ubuntu.com/t/32569) - -## Related information - -* [Appliance command reference](https://discourse.ubuntu.com/t/39525) diff --git a/howto/monitor/landing.md b/howto/monitor/landing.md index 311632fc..bdf2c318 100644 --- a/howto/monitor/landing.md +++ b/howto/monitor/landing.md @@ -1,6 +1,9 @@ +(howto-monitor-anbox)= +# How to monitor Anbox Cloud + Anbox Cloud gathers various performance metrics and makes them accessible through API endpoints. While Anbox Cloud does not provide its own observability solution, it supports implementing and integrating custom solutions for monitoring performance. -See [Prometheus metrics](https://discourse.ubuntu.com/t/prometheus-metrics/19521) for a list of available metrics and how to access them. [LXD Metric exporter for instances](https://discuss.linuxcontainers.org/t/lxd-metric-exporter-for-instances/11735) has a list of metrics available through LXD. +See {ref}`ref-prometheus-metrics` for a list of available metrics and how to access them. [LXD Metric exporter for instances](https://discuss.linuxcontainers.org/t/lxd-metric-exporter-for-instances/11735) has a list of metrics available through LXD. The implementation of a monitoring or observability solution depends on your specific use case and the tools that you want to use. See [Open source observability for enterprises](https://ubuntu.com/observability) for an overview of observability tools and stacks that are recommended and supported by Canonical. In particular, see the [Canonical Observability Stack (LMA2)](https://juju.is/docs/lma2). diff --git a/howto/port/architecture.md b/howto/port/architecture.md index babe257d..a42aa6f8 100644 --- a/howto/port/architecture.md +++ b/howto/port/architecture.md @@ -1,3 +1,6 @@ +(howto-choose-apk-architecture)= +# How to choose APK architecture + In most cases, an Android app is not distributed as a universal APK. If the app contains native libraries, the [ABI split approach](https://developer.android.com/studio/build/configure-apk-splits) is used to produce different APK files for the different architectures. Before creating an application in AMS, you must determine which architecture to use. There are several ways to detect for what architecture an APK's native libraries are built. Since an APK file is just a zip file, a straight-forward way to determine the available architectures is to unzip the APK file and check the sub-folders in the `libs` folder. Typically, they are: diff --git a/howto/port/configure-watchdog.md b/howto/port/configure-watchdog.md index f3fb40c4..10f2dd65 100644 --- a/howto/port/configure-watchdog.md +++ b/howto/port/configure-watchdog.md @@ -1,4 +1,7 @@ -The [watchdog](https://discourse.ubuntu.com/t/application-manifest/24197#watchdog-5) monitors the app installed by the boot package. By default, it terminates the instance if the app crashes or is moved to the background. +(howto-configure-watchdog)= +# How to configure the watchdog + +The {ref}`sec-application-manifest-watchdog` monitors the app installed by the boot package. By default, it terminates the instance if the app crashes or is moved to the background. ## Disable the watchdog diff --git a/howto/port/install-system-app.md b/howto/port/install-system-app.md index e5b5996c..8f9d98f6 100644 --- a/howto/port/install-system-app.md +++ b/howto/port/install-system-app.md @@ -1,6 +1,11 @@ +(howto-install-apk-system-app)= +# How to install an APK as a system app + Usually, Anbox Cloud installs APKs as user apps in the Android container. It is possible to install apps as system apps though. -[note type="information" status="Note"]Installing apps as system apps is not supported on AAOS images.[/note] +```{note} +Installing apps as system apps is not supported on AAOS images. +``` A user app is normally signed by the developer and has restricted permissions at runtime. A system app, on the other hand, is usually [signed with the platform key](https://source.android.com/devices/tech/ota/sign_builds) when building an Android image. It is pre-installed under the system partition and runs a process with some ["signature" protection level permissions](https://developer.android.com/guide/topics/manifest/permission-element.html#plevel) in the Android container. @@ -19,7 +24,7 @@ Installing a user app as a system app in an Android container requires the follo When the application is created successfully, the APK will be installed as a system app in the Android container. -### Make a system app +## Make a system app To build your app as a system app instead of a user app, add the attribute `android:sharedUserId="android.uid.system"` into the `` tag in the `AndroidManifest.xml` file of your Android app. This attribute will allow the app to run a process with system privileges. @@ -34,11 +39,11 @@ To build your app as a system app instead of a user app, add the attribute `andr Then build and sign the application alongside with other Android applications when building your Android image. Alternatively, sign it with [Android Studio](https://developer.android.com/studio/publish/app-signing). This method does not require the system platform key. Instead, you can use the keys that are generated from Android Studio to sign the application. -### Create an addon +## Create an addon To install the signed APK as a system app in the Android container, create an addon and invoke the `aam install-system-app` command in a `pre-start` hook. -Follow the [tutorial](https://discourse.ubuntu.com/t/creating-an-addon/25284) to create the basic layout of an addon, with a `manifest.yaml` file and a `hooks` folder. Place the APK into the addon folder and create a `pre-start` hook with the following content (assuming that the APK file is named `app.apk`): +Follow the {ref}`tut-create-addon` tutorial to create the basic layout of an addon, with a `manifest.yaml` file and a `hooks` folder. Place the APK into the addon folder and create a `pre-start` hook with the following content (assuming that the APK file is named `app.apk`): ```bash #!/bin/bash -ex @@ -70,7 +75,7 @@ Add this addon to AMS with the following command: amc addon add install-system-app . -### Include the addon in an application +## Include the addon in an application To use this addon in an application, include the addon name under `addons` in the application manifest file when creating an application. You must also enable the feature `allow_custom_system_signatures`, which ensures that the `aam install-system-app` command that is invoked in the `pre-start` hook of the addon works properly. diff --git a/howto/port/landing.md b/howto/port/landing.md index 2be078fb..840f2d70 100644 --- a/howto/port/landing.md +++ b/howto/port/landing.md @@ -1,8 +1,21 @@ +(howto-port-android-apps)= +# How to port Android apps + When porting an Android app to Anbox Cloud (usually in the form of an APK), there are a few issues that might cause your app to not function properly: * Missing dependencies, most importantly to Google Play services. Google Play services are not supported by Anbox Cloud, and apps that require Google Play services can therefore not be ported to Anbox Cloud. -* Missing runtime permissions. See [How to grant runtime permissions](https://discourse.ubuntu.com/t/grant-runtime-permissions/26054) for instructions on how to grant the required permissions. -* Mismatched architecture. See [How to choose APK architecture](https://discourse.ubuntu.com/t/choose-apk-architecture/26055) for information on which architecture you should choose. -* App size. See [How to port APKs with OBB files](https://discourse.ubuntu.com/t/port-apks-with-obb-files/26056) for instructions on how to port large APKs. -* Strict watchdog restrictions. See [How to configure the watchdog](https://discourse.ubuntu.com/t/configure-the-watchdog/26057) if you want to turn the watchdog off for debugging or configure it to not trigger for specific apps. -* Install an APK as a system app. See [How to install an APK as a system app](https://discourse.ubuntu.com/t/install-an-apk-as-a-system-app/27086) if you want to install a user app as a system app running in an Android container. +* Missing runtime permissions. See {ref}`howto-grant-runtime-permissions` for instructions on how to grant the required permissions. +* Mismatched architecture. See {ref}`howto-choose-apk-architecture` for information on which architecture you should choose. +* App size. See {ref}`howto-exchange-oob-data` for instructions on how to port large APKs. +* Strict watchdog restrictions. See {ref}`howto-configure-watchdog` if you want to turn the watchdog off for debugging or configure it to not trigger for specific apps. +* Install an APK as a system app. See {ref}`howto-install-apk-system-app` if you want to install a user app as a system app running in an Android container. + +```{toctree} +:hidden: + +Choose APK architecture +Configure Watchdog +Grant runtime permissions to app +Install APK as system app +Port APKs with OBB file +``` diff --git a/howto/port/obb-files.md b/howto/port/obb-files.md index 998fce21..5ff6b37b 100644 --- a/howto/port/obb-files.md +++ b/howto/port/obb-files.md @@ -1,3 +1,6 @@ +(howto-port-apk-oob)= +# How to port APKs with OBB files + Google Play has a limit on how big an APK file can be (see [APK Expansion Files](https://developer.android.com/google/play/expansion-files.html)). Larger Android apps must be split up into the main part as an APK file and the expansion part as an OBB file: - APK: Contains the executables and native libraries (`*.so` files), plugins, basic assets and data required by the application to load for the first time. @@ -39,7 +42,7 @@ Let's assume that you have an application that consists of an APK file and an OB The target location of the OBB file varies depending on the app. Some apps load the OBB file from the SD card (`/sdcard/Android/obb/`), while others load it from the device's internal storage (`/data/media/obb`). - If an OBB file is not properly installed in the instance, the app might not function as expected. Some apps exit immediately if the required OBB file is not found, which triggers the [watchdog](https://discourse.ubuntu.com/t/application-manifest/24197#watchdog-5) and causes the instance to end up in an error state. + If an OBB file is not properly installed in the instance, the app might not function as expected. Some apps exit immediately if the required OBB file is not found, which triggers the watchdog (see {ref}`sec-application-manifest-watchdog`) and causes the instance to end up in an error state. 1. Create the application: diff --git a/howto/port/permissions.md b/howto/port/permissions.md index 2e65565d..e096e3ed 100644 --- a/howto/port/permissions.md +++ b/howto/port/permissions.md @@ -1,3 +1,6 @@ +(howto-grant-runtime-permissions)= +# How to grant runtime permissions + An Anbox Cloud application cannot automatically grant runtime permissions to the app it runs upon creation. Therefore, you must specify the permissions that are required to run the Android app in the application manifest of the Anbox Cloud application. When creating the application in AMS, Anbox Cloud will then grant the specified permissions. To list all required runtime permissions of an Android app, use [AAPT2](https://developer.android.com/studio/command-line/aapt2): diff --git a/howto/stream/access.md b/howto/stream/access.md index 04237bf3..b1f391e9 100644 --- a/howto/stream/access.md +++ b/howto/stream/access.md @@ -1,3 +1,6 @@ +(howto-access-stream-gateway)= +# How to access the stream gateway + Similar to the Anbox Management Service (AMS), the stream gateway exposes its API over an HTTP interface. Clients can be anything from the Anbox Cloud web dashboard to any custom client that you develop. ## Access the stream gateway @@ -38,10 +41,10 @@ curl -X GET https://20.234.75.29:4000/1.0/sessions \ curl -X GET https://20.234.75.29:4000/1.0/sessions?api_token=AgEUYW5ib3...QSyzaA_GHLYQ ``` -[note type="information" status="Note"] +```{note} - The Anbox Stream SDK handles the token automatically for all its requests. - The token does not get renewed automatically. If it expires, create a new token. -[/note] +``` ### Deleting a token @@ -55,9 +58,9 @@ If you are running the Anbox Cloud Appliance, use the following command: Type `anbox-stream-gateway --help` to list all commands. -## Related information +## Related topics -* [About application streaming](https://discourse.ubuntu.com/t/17769) -* [Anbox Management Service (AMS)](https://discourse.ubuntu.com/t/24321) -* [Anbox Cloud streaming SDK](https://discourse.ubuntu.com/t/17844#anbox-cloud-streaming-sdk-8) -* [Set up a stream client](https://discourse.ubuntu.com/t/37328) +* {ref}`exp-application-streaming` +* {ref}`exp-ams` +* {ref}`tut-set-up-stream-client` +* {ref}`sec-streaming-sdk` diff --git a/howto/stream/client-side-keyboard.md b/howto/stream/client-side-keyboard.md index 9b44e7c6..24b9e725 100644 --- a/howto/stream/client-side-keyboard.md +++ b/howto/stream/client-side-keyboard.md @@ -1,3 +1,7 @@ + +(howto-integrate-virtual-keyboard)= +# How to integrate a client-side virtual keyboard + The Anbox Streaming SDK enables developers to build a hybrid mobile application that can integrate the features that Anbox Cloud provides. It comes with an [Android library](https://developer.android.com/studio/projects/android-library) that offers easy-to-use native components like Anbox WebView, which extends the AOSP [WebView](https://developer.android.com/reference/android/webkit/WebView). It provides better handling of text input for the hybrid application that loads the Anbox Streaming JavaScript SDK with an embedded WebView for video streaming. You can use Anbox WebView to quickly integrate a client-side virtual keyboard feature into your mobile application. This client-side virtual keyboard can send text to the Android container on the fly when typing: @@ -5,13 +9,13 @@ You can use Anbox WebView to quickly integrate a client-side virtual keyboard fe * When the text editor of the application in the instance gains focus, the client-side virtual keyboard pops up, and it disappears when the focus moves away. * When typing on the client-side virtual keyboard, the input text is sent to the Android container and displayed in the running application. -The following steps provide general instructions for integrating the client-side virtual keyboard feature into an Android application. See [Customising the virtual keyboard](#customising-the-virtual-keyboard-4) for additional implementation options. +The following steps provide general instructions for integrating the client-side virtual keyboard feature into an Android application. See [Customising the virtual keyboard](#customising-the-virtual-keyboard) for additional implementation options. For the complete implementation details, refer to the `enhanced_webview_streaming` example in the `example/android` folder. -[note type="information" status="Note"] +```{note} To enable the app running in the Android container to receive the texts sent from the client-side virtual keyboard, you must declare the feature `enable_anbox_ime` in the application manifest file when creating an application. -[/note] +``` ## 1. Import the AAR library diff --git a/howto/stream/landing.md b/howto/stream/landing.md index 131c7afe..91148378 100644 --- a/howto/stream/landing.md +++ b/howto/stream/landing.md @@ -1,5 +1,16 @@ -The guides in this section describe how to use the Streaming Stack to implement specific streaming features in your application. +(howto-streaming)= +# How to implement streaming -See [About application streaming](https://discourse.ubuntu.com/t/streaming-android-applications/17769) for an introduction to the Streaming Stack. +The following guides in this section describe how to use the Streaming Stack to implement specific streaming features in your application. -For an introduction to the Streaming SDK, see [Anbox Streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8). +```{toctree} +:titlesonly: + +Access stream gateway +Exchange out-of-band-data +Integrate client side keyboard +``` + +See {ref}`exp-application-streaming` for an introduction to the Streaming Stack. + +For an introduction to the Streaming SDK, see {ref}`sec-streaming-sdk`. diff --git a/howto/stream/oob-data.md b/howto/stream/oob-data.md index ad87eec5..2a934a63 100644 --- a/howto/stream/oob-data.md +++ b/howto/stream/oob-data.md @@ -1,29 +1,33 @@ +(howto-exchange-oob-data)= +# How to exchange out-of-band data + Enabling out-of-band (OOB) data transmission between an Android application and a WebRTC client makes it possible to exchange data and trigger actions between an Android application and a WebRTC client. Anbox Cloud provides two versions of this OOB data exchange: -* [Version 2](#version-2-1) provides a full-duplex bidirectional data transmission mode in which data can flow in both directions at the same time. +* [Version 2](#version-2) provides a full-duplex bidirectional data transmission mode in which data can flow in both directions at the same time. Use this version if you start your implementation now. If you already have an existing implementation, you should plan to update it to use version 2. -* [Version 1](#version-1-10) enables Android application developers to trigger an action from an Android application running in an [instance](https://discourse.ubuntu.com/t/26204#instance) and forward it to a WebRTC client through the Anbox WebRTC platform. When Anbox receives the action, as one peer of the WebRTC platform, the action is propagated from Anbox to the remote peer (the WebRTC client) through a WebRTC data channel. The client can then react to the action received from the remote peer and respond accordingly on the UI. +* [Version 1](#version-1) enables Android application developers to trigger an action from an Android application running in an instance and forward it to a WebRTC client through the Anbox WebRTC platform. When Anbox receives the action, as one peer of the WebRTC platform, the action is propagated from Anbox to the remote peer (the WebRTC client) through a WebRTC data channel. The client can then react to the action received from the remote peer and respond accordingly on the UI. This version supports only half-duplex data transmission. It allows sending data from an Android application to a WebRTC client through the Anbox WebRTC platform, but it is not possible to receive data from the WebRTC client to an Android application. -[note type="caution" status="Warning"] -The support for [version 1](#version-1-10) of the out-of-band data exchange between an Android application and a WebRTC client has been removed in the Anbox Cloud 1.16 release. Therefore, you should migrate your integration of version 1 of the OOB data exchange to [version 2](#version-2-1) for full-duplex data transmission and better performance. -[/note] +```{caution} +The support for [version 1](#version-1) of the out-of-band data exchange between an Android application and a WebRTC client has been removed in the Anbox Cloud 1.16 release. Therefore, you should migrate your integration of version 1 of the OOB data exchange to [version 2](#version-2) for full-duplex data transmission and better performance. +``` See the instructions for exchanging OOB data using a specific implementation version below: -* [Version 2](#version-2-1) -* [Version 1](#version-1-10) +* [Version 2](#version-2) +* [Version 1](#version-1) +(sec-oob-data-version-2)= ## Version 2 The following instructions will walk you through how to set up data channels and perform data transmission in both directions between an Android application and a WebRTC platform. ### Web application -In your web-based client application, import the [Anbox Streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8). +In your web-based client application, import the {ref}`sec-streaming-sdk`. Create a data channel (named `foo` in the following example) under the `dataChannels` property of an `AnboxStream` object and register event handlers that respond to the events sent from an Android application: @@ -52,9 +56,9 @@ let stream = new AnboxStream({ }); ``` -[note type="information" status="Note"] +```{note} An `AnboxStream` object can create a maximum of five data channels. If the number of data channels exceeds the allowed maximum, an exception is thrown when instantiating the `AnboxStream` object. -[/note] +``` To launch a new WebRTC session, the client must call `stream.connect()`. The `AnboxStream` object then builds up a WebRTC native data channel internally, based on the name declared under its `dataChannels` property for peer-to-peer communication (`foo` in the example). @@ -115,7 +119,9 @@ To build up the communication bridge between an Android application and the Anbo The `anbox-webrtc-data-proxy` system daemon runs in the instance and registers an Android system service named `org.anbox.webrtc.IDataProxyService`. This service allows Android developers to easily make use of binder interprocess communication (IPC) for data communication between an Android application and the Anbox WebRTC platform through a file descriptor. -[note type="information" status="Note"]To interact with the `org.anbox.webrtc.IDataProxyService` system service, the Android application must be [installed as a system app](https://discourse.ubuntu.com/t/how-to-install-an-apk-as-a-system-app/27086). [/note] +```{note} +To interact with the `org.anbox.webrtc.IDataProxyService` system service, the Android application must be installed as a system app. See {ref}`howto-install-apk-system-app` for instructions. +``` #### Get notified about the availability of data channels @@ -268,11 +274,12 @@ try { For a complete Android example, see the [out_of_band_v2](https://github.com/canonical/anbox-streaming-sdk/tree/master/examples/android/out_of_band_v2) project. +(sec-oob-data-version-1)= ## Version 1 -[note type="caution" status="Warning"] +```{caution} The support for version 1 of the out-of-band data exchange between an Android application and a WebRTC client has been removed in the Anbox Cloud 1.16 release. -[/note] +``` ### Android application @@ -359,9 +366,7 @@ in JavaScript, C or C++ by using the Anbox Streaming SDK. #### Web application -For a web-based application, you can use the JavaScript SDK which you can find under -[Anbox Cloud SDKs](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8). To receive the data sent from the Android application -running in the instance, implement the `messageReceived` callback +For a web-based application, you can use the JavaScript SDK which you can find under {ref}`sec-streaming-sdk`. To receive the data sent from the Android application running in the instance, implement the `messageReceived` callback of the `AnboxStream` object: ``` diff --git a/howto/troubleshoot/application-creation.md b/howto/troubleshoot/application-creation.md index f5d3c0f7..fdc5f24f 100644 --- a/howto/troubleshoot/application-creation.md +++ b/howto/troubleshoot/application-creation.md @@ -1,3 +1,6 @@ +(howto-ts-application-creation-issues)= +# Troubleshoot issues with application creation + You might encounter the following issues when creating an application. ## Application manifest diff --git a/howto/troubleshoot/dashboard-issues.md b/howto/troubleshoot/dashboard-issues.md index dd645bf6..09f60ee9 100644 --- a/howto/troubleshoot/dashboard-issues.md +++ b/howto/troubleshoot/dashboard-issues.md @@ -1,3 +1,8 @@ +(howto-ts-web-dashboard)= +# Troubleshoot issues while using the web dashboard + +You might encounter the following issues when using the dashboard. + ## Session with an Error status *Applies to: Anbox Cloud, Anbox Cloud Appliance* @@ -7,8 +12,8 @@ On the **Sessions** page, you could see a session with an **Error** status when ![Session with an Error status|690x440](https://assets.ubuntu.com/v1/43e5fac7-session-error.png) Try the following actions: -* Verify if you have [sufficient resources](https://discourse.ubuntu.com/t/capacity-planning/28717) for instance/application creation. -* Check if all the nodes are in [`unschedulable`](https://discourse.ubuntu.com/t/ams-configuration/20872) mode. +* Verify if you have sufficient resources for instance/application creation. See {ref}`exp-capacity-planning` for more information. +* Check if all the nodes are in `unschedulable` mode. See {ref}`sec-node-configuration` for more information. ## Session does not start @@ -18,7 +23,7 @@ A session does not start and the session details page displays the following err ![Session does not start|690x440](https://assets.ubuntu.com/v1/4658bad5-session-does-not-start.png) -[Check the instance logs](https://discourse.ubuntu.com/t/24329) to find reasons for the session failure. +See {ref}`howto-view-instance-logs` to find reasons for the session failure. ## Instances(s) in Error status @@ -36,8 +41,8 @@ Click on the corresponding **INSTANCE ID** and check the instance details page f ![Instance details page|690x440](https://assets.ubuntu.com/v1/590c9eea-instance-details-error.png) The **Error Message field** can give you a starting point for identifying the issue. Some reasons for an instance to go into error status could be: -* Insufficient resources. Refer [Capacity planning](https://discourse.ubuntu.com/t/capacity-planning/28717). -* Occasionally, access to Ubuntu archives could be a problem when creating an application. As an immediate workaround, you could disable the security update by running `amc config set instance.security_updates false` or explicitly set `amc config set instance.api_mirror ` to configure an instance to use a different APT mirror. See [AMS configuration](https://discourse.ubuntu.com/t/ams-configuration/20872) for more details. +* Insufficient resources. Refer to {ref}`exp-capacity-planning`. +* Occasionally, access to Ubuntu archives could be a problem when creating an application. As an immediate workaround, you could disable the security update by running `amc config set instance.security_updates false` or explicitly set `amc config set instance.api_mirror ` to configure an instance to use a different APT mirror. See {ref}`ref-ams-configuration` for more details. If the reason for the instance failure is not obvious from the **Error Message**, check the **Logs** tab for more information. @@ -51,7 +56,7 @@ Logs are unavailable for an instance when: * The instance is not in error status. * Occasionally, the instance could have ended up with an error status due to insufficient resources but there are no log files because the application bootstrap process succeeded. -Normally, the logs are available if the instance is in an error state. If the instance is in the error state and yet there are no logs available, [check if you have enough resources](https://discourse.ubuntu.com/t/capacity-planning/28717). +Normally, the logs are available if the instance is in an error state. If the instance is in the error state and yet there are no logs available, check if you have enough resources. See {ref}`exp-capacity-planning` for more information. ## Terminal is unavailable for an instance diff --git a/howto/troubleshoot/initial-setup.md b/howto/troubleshoot/initial-setup.md index 9016796f..753716d6 100644 --- a/howto/troubleshoot/initial-setup.md +++ b/howto/troubleshoot/initial-setup.md @@ -1,3 +1,6 @@ +(howto-ts-initial-setup)= +# Troubleshoot issues with initial setup + You might encounter the following issues while setting up your system. ## Juju hook installation failure diff --git a/howto/troubleshoot/instance-failures.md b/howto/troubleshoot/instance-failures.md index 802cd9fb..16fbd179 100644 --- a/howto/troubleshoot/instance-failures.md +++ b/howto/troubleshoot/instance-failures.md @@ -1,3 +1,6 @@ +(howto-ts-instance-failures)= +# Troubleshoot instance failures + The following information should help you in determining why your instance failed. ## More information on instance failures @@ -8,7 +11,7 @@ The following information should help you in determining why your instance faile If an instance fails to start, its status is set to `error`. Anbox Management Service (AMS) automatically fetches several log files from the instance and makes them available for further inspection. The log files can provide information on why the instance failed to start. The reason for instance failure may not always be simple and easy to resolve because of a number of variable factors, for example, the application that the instance is hosting or any installed addons. -See [How to view the instance logs](https://discourse.ubuntu.com/t/24329) for instructions on how to access the instance log files. +See {ref}`howto-view-instance-logs` for instructions on how to access the instance log files. ## Published application version not found @@ -16,4 +19,4 @@ See [How to view the instance logs](https://discourse.ubuntu.com/t/24329) for in > When launching an instance for an application, I get an error that mentions "published application version not found". Why? -If you launch an instance by only specifying the application ID and the application has no published version yet, you must explicitly specify the version that you want to launch or publish a version of the application. See [How to launch application instances](https://discourse.ubuntu.com/t/24327#launch-application-instances-1) and [How to publish application versions](https://discourse.ubuntu.com/t/update-an-application/24201#publish-application-versions-1) for more information. \ No newline at end of file +If you launch an instance by only specifying the application ID and the application has no published version yet, you must explicitly specify the version that you want to launch or publish a version of the application. See {ref}`sec-launch-application-instances` and {ref}`sec-publish-app-versions` for more information. \ No newline at end of file diff --git a/howto/troubleshoot/landing.md b/howto/troubleshoot/landing.md index d0873683..c05bad2e 100644 --- a/howto/troubleshoot/landing.md +++ b/howto/troubleshoot/landing.md @@ -1,17 +1,28 @@ -The topics in this guide describe some commonly encountered problems with Anbox Cloud and provide instructions for resolving them. If you encounter an issue with Anbox Cloud, check if any of the following scenarios help in resolving your issue. +(howto-ts-anbox-cloud)= +# How to troubleshoot Anbox Cloud -[note type="information" status="Note"] If the deployment is older than 3 months, you must upgrade Anbox Cloud to the latest version and see if the required fixes are already part of the upgrade. See [How to upgrade Anbox Cloud](https://discourse.ubuntu.com/t/how-to-upgrade-anbox-cloud/17750) for upgrade instructions.[/note] +The following troubleshooting guides describe some commonly encountered problems with Anbox Cloud and provide instructions for resolving them. If you encounter an issue with Anbox Cloud, check if any of the following scenarios help in resolving your issue. -* [Troubleshoot issues with initial setup](https://discourse.ubuntu.com/t/35704) -* [Troubleshoot instance failures](https://discourse.ubuntu.com/t/35703) -* [Troubleshoot issues with application creation](https://discourse.ubuntu.com/t/35702) -* [Troubleshoot issues with LXD clustering](https://discourse.ubuntu.com/t/35705) -* [Troubleshoot issues with dashboard](https://discourse.ubuntu.com/t/36105) -* [Troubleshoot issues with streaming](https://discourse.ubuntu.com/t/31341) +```{toctree} +:titlesonly: + +Instance failures +Issues with application creation +Issues with clustering +Issues with initial setup +Issues with streaming +Issues with web dashboard +View logs +``` + +```{note} +If the deployment is older than 3 months, you must upgrade Anbox Cloud to the latest version and see if the required fixes are already part of the upgrade. See {ref}`howto-upgrade-anbox-cloud` for upgrade instructions. +``` If you still need help, use any of the following utilities to collect troubleshooting information and report an [issue](https://bugs.launchpad.net/anbox-cloud/+filebug). -[note type="information" status="Note"] The following utilities could be applicable for the regular Anbox Cloud deployed with Juju or for the Anbox Cloud Appliance or both. The *Applies to* tag in each section indicates whether it is applicable to a particular variant. To know more about Anbox Cloud variants, see [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1).[/note] + +The following utilities could be applicable for the regular Anbox Cloud deployed with Juju or for the Anbox Cloud Appliance or both. The *Applies to* tag in each section indicates whether it is applicable to a particular variant. To know more about Anbox Cloud variants, see {ref}`sec-variants`. ## Juju crashdump @@ -59,9 +70,4 @@ saves it to the local ``. This process might take a few seconds. If an instance fails to start or a runtime error occurs, AMS collects relevant log files from the instance and makes them available for inspection. -Use `amc show ` command to list the available logs. See [View stored logs](https://discourse.ubuntu.com/t/24329#view-stored-logs-2) for an example of such a stored log. - -## Related topics - -* [View Anbox Cloud logs](https://discourse.ubuntu.com/t/17771) -* [View instance logs](https://discourse.ubuntu.com/t/24329) +Use `amc show ` command to list the available logs. See {ref}`howto-view-instance-logs` for information on viewing the instance logs. diff --git a/howto/troubleshoot/logs.md b/howto/troubleshoot/logs.md index 7a729478..72124339 100644 --- a/howto/troubleshoot/logs.md +++ b/howto/troubleshoot/logs.md @@ -1,11 +1,14 @@ +(howto-ts-view-logs)= +# How to view logs + There are two types of logs that help you understand what is happening in your Anbox Cloud installation: -- Logs for the applications that you are running, on a cluster or node level. See [How to view the instance logs](https://discourse.ubuntu.com/t/24329) for information about this type of logs. +- Logs for the applications that you are running, on a cluster or node level. See {ref}`howto-view-instance-logs` for more information. - Infrastructure logs for the deployment. These logs differ depending on whether you run a full Anbox Cloud deployment or the Anbox Cloud Appliance. See the following sections for more information. ## View logs for Anbox Cloud -The Anbox Cloud deployment has centralised logging set up as default. Each unit in your cluster automatically sends logging information to the controller based on the current [logging level](#logging-level-4). You can use the Juju command line to easily inspect these logs and to change the logging level. +The Anbox Cloud deployment has centralised logging set up as default. Each unit in your cluster automatically sends logging information to the controller based on the current [logging level](#logging-level). You can use the Juju command line to easily inspect these logs and to change the logging level. To view the logs from the current controller and model, simply run: diff --git a/howto/troubleshoot/lxd-cluster.md b/howto/troubleshoot/lxd-cluster.md index 7051873d..075d9cc0 100644 --- a/howto/troubleshoot/lxd-cluster.md +++ b/howto/troubleshoot/lxd-cluster.md @@ -1,3 +1,6 @@ +(howto-ts-lxd-clustering)= +# Troubleshoot issues with LXD clustering + The following issues might occur if you use clustering. ## AMS hook failed: `lxd-relation-changed` @@ -43,7 +46,9 @@ The easiest way to make the AMS unit work again is to remove the faulty LXD node juju remove-unit --force lxd/5 -[note type="information" status="Note"]Add `--destroy-storage` to the command if you allocated dedicated storage for LXD.[/note] +```{note} +Add `--destroy-storage` to the command if you allocated dedicated storage for LXD. +``` After the LXD unit is successfully removed, resolve the failed hook of the AMS unit. To do that, first disable automatic retries to prevent Juju from re-running the failed hook: diff --git a/howto/troubleshoot/streaming-issues.md b/howto/troubleshoot/streaming-issues.md index abfed142..2db5eef3 100644 --- a/howto/troubleshoot/streaming-issues.md +++ b/howto/troubleshoot/streaming-issues.md @@ -1,3 +1,6 @@ +(howto-ts-streaming-issues)= +# Troubleshoot streaming issues + Debugging issues that occur when streaming your application can be tricky. The following instructions give you some pointers on how to start tracking down streaming issues. First of all, check the error message that occurs. Unfortunately, it is often hard to determine why a connection fails, which is why the error message does not always give a clear indication of the source of the error. Typical errors are covered though, so in these cases, the error message should give you an idea on where to look. @@ -55,4 +58,4 @@ If streaming starts, but keeps stalling and the quality is bad, the reason is us In this case, check the WebRTC log to see if there is a high packet loss, and if so, in what situations it occurs. Most likely it is due to a bad network connection between the web dashboard (or your client application) and Anbox Cloud. -See [About performance > Client devices](https://discourse.ubuntu.com/t/about-performance/29416#client-devices) for more information. +See {ref}`sec-client-devices` for more information. diff --git a/howto/update/control.md b/howto/update/control.md index 8f2b5f4c..e0a227ad 100644 --- a/howto/update/control.md +++ b/howto/update/control.md @@ -1,3 +1,6 @@ +(howto-control-updates)= +# How to control updates + For security reasons, you should keep your systems up-to-date at all times. To ensure this, [snaps](https://snapcraft.io/about) update automatically, and the snap daemon is by default configured to check for updates four times a day. In a production environment, this update behaviour might cause problems in some cases. For example: diff --git a/howto/update/landing.md b/howto/update/landing.md index 6c12a72c..f7825795 100644 --- a/howto/update/landing.md +++ b/howto/update/landing.md @@ -1,3 +1,16 @@ -The guides in this section describe how to update your Anbox Cloud or Anbox Cloud Appliance installation. +(howto-update)= +# How to update Anbox Cloud +The following guides in this section describe how to update your Anbox Cloud or Anbox Cloud Appliance installation. + +```{note} If possible, Anbox Cloud automatically enables [Livepatch](https://ubuntu.com/security/livepatch). Livepatch applies critical Linux kernel patches with zero downtime. You can check whether Livepatch is available for your platform by running `pro status`. +``` + +```{toctree} +:titlesonly: + +Control updates +Upgrade Anbox Cloud Appliance +Upgrade Anbox Cloud (regular) +``` diff --git a/howto/update/upgrade-anbox.md b/howto/update/upgrade-anbox.md index 69ba53c3..de62f3b5 100644 --- a/howto/update/upgrade-anbox.md +++ b/howto/update/upgrade-anbox.md @@ -1,4 +1,9 @@ -[note type="information" status="Note"]If you're interested in getting notified for the latest Anbox Cloud releases, make sure you subscribe to notifications on the [announcements category](https://discourse.ubuntu.com/c/anbox-cloud/announcements/55) on the Anbox Cloud discourse.[/note] +(howto-upgrade-anbox-cloud)= +# How to upgrade Anbox Cloud + +```{note} +If you're interested in getting notified for the latest Anbox Cloud releases, make sure you subscribe to notifications on the [announcements category](https://discourse.ubuntu.com/c/anbox-cloud/announcements/55) on the Anbox Cloud discourse. +``` Anbox Cloud allows upgrades from older versions to newer version. This describes the steps necessary to perform the upgrade. @@ -14,7 +19,7 @@ You should also make sure that: * Your Juju client and controller/models are running the latest version. * You have read the release notes for the version you are upgrading to, which will alert you to any important changes to the operation of your cluster. -[note type="information" status="Note"] +```{note} The following assume you're using Juju >= 3.1. If you're using Juju 2.9, you have to map the following commands: @@ -23,7 +28,7 @@ The following assume you're using Juju >= 3.1. If you're using Juju 2.9, you hav | `juju refresh` | `juju upgrade-charm` | | `juju exec` | `juju run` | -[/note] +``` ## Upgrade OS @@ -46,7 +51,7 @@ If they are not, run the following command to do so: ## Check Juju version -Before you upgrade, check the required [Juju version](https://discourse.ubuntu.com/t/installation-requirements/17734#juju-version-10). +Before you upgrade, check the required {ref}`sec-juju-version-requirements`. If your deployment uses an earlier Juju version, you must upgrade your controller and all models first. See the [Juju documentation](https://juju.is/docs/olm/upgrade-models) for instructions on how to upgrade the Juju controller and all models to a newer Juju version. @@ -54,17 +59,15 @@ If your deployment uses an earlier Juju version, you must upgrade your controlle The deployed Juju charms need to be upgraded next. -[note type="information" status="Note"] - -- You can find a list of all charm, snap, bundle and Debian package versions for each Anbox Cloud release in the [component versions](https://discourse.ubuntu.com/t/component-versions/21413) overview. This also includes the charm and bundle revisions and channels for each release. +```{note} +- You can find a list of all charm, snap, bundle and Debian package versions for each Anbox Cloud release in the {ref}`ref-component-versions` overview. This also includes the charm and bundle revisions and channels for each release. - If you want to deploy a particular revision of a charm, you can do so by adding `--revision=` to the `juju upgrade-charm` command. - Starting with the 1.21 release, the NATS charm has been switched from its [older version](https://charmhub.io/nats-charmers-nats) to a [newer version](https://charmhub.io/nats) on Charmhub. This switch does not have any breaking changes from a user's perspective but since the framework of the charm has been overhauled, the upgrade to the new charm would require users to `switch` the charm's source while refreshing/updating the charm. - Starting with the 1.22 release, the `anbox-stream-agent` charm has a new relation `client` which can be used to register new clients for the Anbox Stream Agent. This new relation is used by the new AMS charm to create stream-enabled instances using the `--enable-streaming` option. For deployments using the bundles from or after 1.22 release, the relation is created automatically. For users upgrading from older versions of Anbox Cloud, the relation needs to be manually created using `juju relate anbox-stream-agent:client ams:agent` after upgrading both the `ams` and the `anbox-stream-agent` charms to 1.22. - -[/note] +``` For any of the charm upgrades, you can watch the upgrade status by running: @@ -72,9 +75,9 @@ For any of the charm upgrades, you can watch the upgrade status by running: Continue with the next step only when the current step has completed successfully and all units in the output are marked as **active**. -[note type="information" status="Note"] +```{note} If you don't run Anbox Cloud in a high availability configuration, upgrading the charms will cause a short down time of individual service components during the process. -[/note] +``` ### Upgrade infrastructure components @@ -97,9 +100,9 @@ To upgrade the registry, run If you have the streaming stack deployed, you need to update the charms responsible for the control plane next. If you do not use the streaming stack, you can skip this step. -[note type="information" status="Note"] +```{note} If you don't run any of the services in a high availability configuration, upgrading the charms will cause a short down time of the service. -[/note] +``` To upgrade all charms, run the following commands: @@ -109,12 +112,11 @@ To upgrade all charms, run the following commands: juju refresh --channel=1.22/stable coturn juju refresh --channel=latest/stable nats -[note type="information" status="Note"] +```{note} Since the NATS charm has been overhauled to use the modern charm framework (Ops Framework), a new charm source is needed to upgrade to its latest version. The charm source can be switched or replaced using the following command: juju refresh nats --switch=nats --channel=stable - -[/note] +``` ### Upgrade AMS @@ -140,7 +142,7 @@ In some cases, specifically when you maintain bigger LXD clusters or want to kee This will allow you to run the actual upgrade process for each deployed LXD instance separately. -If you want to remove any nodes from the LXD cluster as part of the manual upgrade process, follow the instructions in [How to scale down a LXD cluster](https://discourse.ubuntu.com/t/how-to-scale-down-a-lxd-cluster/24323) to prepare a node for removal and then remove it from the cluster. +If you want to remove any nodes from the LXD cluster as part of the manual upgrade process, follow the instructions in {ref}`howto-scale-down-cluster` to prepare a node for removal and then remove it from the cluster. Once the unnecessary nodes are dropped, the upgrade for a single LXD deployment unit can be triggered by running: @@ -177,4 +179,4 @@ You can check for the status of an existing application by running: amc application show -In case automatic updates are disabled for applications, AMS cannot update the application. See [Configure automatic application updates](https://discourse.ubuntu.com/t/24201#configure-automatic-application-updates-3) to enable automatic updates or to manually update the applications. +In case automatic updates are disabled for applications, AMS cannot update the application. See {ref}`sec-configure-automatic-app-updates` to enable automatic updates or to manually update the applications. diff --git a/howto/update/upgrade-appliance.md b/howto/update/upgrade-appliance.md index 4902c151..5040b82a 100644 --- a/howto/update/upgrade-appliance.md +++ b/howto/update/upgrade-appliance.md @@ -1,3 +1,6 @@ +(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 @@ -11,7 +14,9 @@ The Anbox Cloud Appliance includes an `upgrade` command which will perform all r reboot-needed: false version: 1.19.0 -[note type="information" status="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.[/note] +```{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: @@ -19,7 +24,9 @@ In the `anbox-cloud-appliance status` command output, the `update-available` fie The appliance will now perform all necessary steps to upgrade to the newer available version. -[note type="information" status="Note"]In case automatic updates are disabled for applications, Anbox Management Service (AMS) cannot update the application. See [Configure automatic application updates](https://discourse.ubuntu.com/t/24201#configure-automatic-application-updates-3) to enable automatic updates or to manually update the applications.[/note] +```{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: diff --git a/images/README.md b/images/README.md index 5906263b..ecbeeecc 100644 --- a/images/README.md +++ b/images/README.md @@ -1,9 +1,13 @@ +--- +orphan: true +--- + # Customise drawio/diagrams.net Load custom shapes: 1. Go to **File** > **Open Library**. -2. Select the `discourse-docs/images/anbox-drawio.xml` file. +2. Select the `anbox-cloud-docs/images/anbox-drawio.xml` file. Configure custom styles and colours: @@ -171,13 +175,13 @@ Configure custom styles and colours: - Use font `ubuntu`. - Standard font size: 15pt -- Use only the provided colours. See the colour palette at https://design.ubuntu.com/brand/colour-palette/ . +- Use only the provided colours. See the colour palette at [`https://design.ubuntu.com/brand/colour-palette/`](https://design.ubuntu.com/brand/colour-palette/) . # Upload images to the asset manager -Images should be uploaded to https://manager.assets.ubuntu.com/ . +Images should be uploaded to [Ubuntu assets](https://assets.ubuntu.com/manager) . -To do this from the command line, get an API token and install https://github.com/canonical/canonicalwebteam.upload-assets +To do this from the command line, get an API token and install [`https://github.com/canonical/canonicalwebteam.upload-assets`](https://github.com/canonical/canonicalwebteam.upload-assets) Export the required environment variables: diff --git a/index.md b/index.md index 18cdbbb0..ac3a3f8e 100644 --- a/index.md +++ b/index.md @@ -1,3 +1,5 @@ +# Anbox Cloud documentation + Anbox Cloud enables running Android apps on any cloud platform at scale. It uses system containers or virtual machines to run the nested Android containers and [Juju](https://juju.is/) for deployment in a cloud environment. Anbox Cloud supports x86 and Arm64 hardware, providing the same set of features for both architectures. @@ -10,397 +12,38 @@ Due to its highly scalable nature and performance optimisation, delivering devic | | | |--|--| -| [Tutorials](https://discourse.ubuntu.com/t/tutorials/28826)
Get started - a hands-on introduction to Anbox Cloud for new users
| [How-to guides](https://discourse.ubuntu.com/t/how-to-guides/28827)
Step-by-step guides covering key operations and common tasks | -| [Explanation](https://discourse.ubuntu.com/t/explanation/28829)
Concepts - discussion and clarification of key topics, architecture | [Reference](https://discourse.ubuntu.com/t/reference/28828)
Technical information - specifications, APIs | +| [Tutorials](/tutorial/landing.md)
Get started - a hands-on introduction to Anbox Cloud for new users
| [How-to guides](/howto/landing.md)
Step-by-step guides covering key operations and common tasks | +| [Explanation](/explanation/landing.md)
Concepts - discussion and clarification of key topics, architecture | [Reference](/reference/landing.md)
Technical information - specifications, APIs | ## Project and community Anbox Cloud is a Canonical product. It originally grew out of the [Anbox open-source project](https://github.com/anbox), but its code base is now completely independent. -- [Get support through Ubuntu Pro](https://ubuntu.com/support) -- Forums: - - [Ask questions about Anbox Cloud](https://discourse.ubuntu.com/c/anbox-cloud/users/148) - - [Contribute to Anbox Cloud documentation](https://discourse.ubuntu.com/c/anbox-cloud/documentation/50) - - [Give feedback on Anbox Cloud documentation](https://forms.gle/6yzgLbwN8rVYSdvG9) - - [Follow Anbox Cloud release announcements](https://discourse.ubuntu.com/c/anbox-cloud/announcements/55) -- [Release roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359) -- [Release notes](https://discourse.ubuntu.com/t/release-notes/17842) -- [Troubleshoot](https://discourse.ubuntu.com/t/how-to-troubleshoot-anbox-cloud/17837) and [report](https://bugs.launchpad.net/anbox-cloud/+bugs) issues with Anbox Cloud +We welcome community involvement through suggestions, fixes and constructive feedback both on the product and its documentation. You can engage with the Anbox Cloud team and the community using the following channels: -Thinking about using Anbox Cloud for your next project? [Get in touch!](https://anbox-cloud.io/contact-us) +- Engage with the Anbox Cloud team and community: + - [Discourse](https://discourse.ubuntu.com/c/anbox-cloud/users/148) + - [Matrix](https://matrix.to/#/#anbox-cloud:ubuntu.com) +- {ref}`Troubleshoot Anbox Cloud ` +- [Report a bug](https://bugs.launchpad.net/anbox-cloud/+bugs) +- {ref}`contribute` +- [Report an issue with Anbox Cloud documentation](https://github.com/canonical/anbox-cloud-docs/issues/new) + +The following resources help you get familiar with Anbox Cloud, its releases and roadmap: -## Navigation +- {ref}`Release roadmap ` +- {ref}`ref-release-notes` -[details=Navigation] -| Level | Path | Navlink | -| -- | -- | -- | -| 0 | / | [Anbox Cloud documentation](https://discourse.ubuntu.com/t/anbox-cloud-documentation/17029) | -| 0 | | | -| 1 | tutorial/landing | [Tutorials](https://discourse.ubuntu.com/t/tutorials/28826) | -| 2 | tutorial/installing-appliance | [1. Install the appliance](https://discourse.ubuntu.com/t/install-appliance/22681) | -| 2 | tutorial/getting-started-dashboard | [2. Get started using the web dashboard](https://discourse.ubuntu.com/t/getting-started-with-anbox-cloud-web-dashboard/24958)| -| 2 | tutorial/getting-started | [3. Get started using the CLI](https://discourse.ubuntu.com/t/getting-started/17756)| -| 2 | tutorial/stream-client | [4. Set up a stream client (Optional)](https://discourse.ubuntu.com/t/set-up-a-stream-client/37328) | -| 2 | tutorial/getting-started-aaos | [5. Get started with AAOS (Optional)](https://discourse.ubuntu.com/t/create-and-stream-an-aaos-application/45467)| -| 2 | tutorial/creating-addon | [6. Create an addon (Optional)](https://discourse.ubuntu.com/t/creating-an-addon/25284)| -| 0 | | | -| 1 | howto/landing | [How-to guides](https://discourse.ubuntu.com/t/how-to-guides/28827) | -| 2 | howto/install-appliance/landing | [Install the appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702) | -| 3 | howto/install-appliance/aws | [Install on AWS](https://discourse.ubuntu.com/t/how-to-install-the-appliance-on-aws/29703) | -| 3 | howto/install-appliance/azure | [Install on Azure](https://discourse.ubuntu.com/t/how-to-install-the-appliance-on-azure/30824) | -| 3 | howto/install-appliance/google-cloud | [Install on Google Cloud](https://discourse.ubuntu.com/t/36254) | -| 2 | howto/install/landing | [Install Anbox Cloud](https://discourse.ubuntu.com/t/install-anbox-cloud/24336)| -| 3 | howto/install/deploy-juju | [Deploy with Juju](https://discourse.ubuntu.com/t/install-with-juju/17744) | -| 3 | howto/install/deploy-bare-metal | [Deploy on bare metal](https://discourse.ubuntu.com/t/deploy-anbox-cloud-on-bare-metal/26378) | -| 3 | howto/install/customise | [Customise the installation](https://discourse.ubuntu.com/t/installation-customizing/17747)| -| 3 | howto/install/high-availability | [Enable High Availability](https://discourse.ubuntu.com/t/high-availability/17754)| -| 3 | howto/install/validate | [Validate the deployment](https://discourse.ubuntu.com/t/validation/20329)| -| 2 | howto/update/landing | [Update an installation](https://discourse.ubuntu.com/t/update-your-installation/24331)| -| 3 | howto/update/control | [Control updates](https://discourse.ubuntu.com/t/control-updates/24959)| -| 3 | howto/update/upgrade-appliance | [Upgrade the appliance](https://discourse.ubuntu.com/t/upgrade-anbox-cloud-appliance/24186)| -| 3 | howto/update/upgrade-anbox | [Upgrade Anbox Cloud](https://discourse.ubuntu.com/t/upgrading-from-previous-versions/17750)| -| 2 | howto/manage/landing| [Manage Anbox Cloud](https://discourse.ubuntu.com/t/manage-anbox-cloud/24337) | -| 3 | howto/manage/tls-for-appliance | [Set up TLS for appliance](https://discourse.ubuntu.com/t/set-up-tls-for-the-anbox-cloud-appliance/28552) | -| 3 | howto/manage/images | [Manage Anbox Cloud images](https://discourse.ubuntu.com/t/managing-images/17758)| -| 3 | howto/manage/ams-access | [Control AMS remotely](https://discourse.ubuntu.com/t/managing-ams-access/17774)| -| 3 | howto/manage/benchmarks | [Run benchmarks](https://discourse.ubuntu.com/t/benchmarking-a-deployment/17770)| -| 3 | howto/manage/resize-storage | [Resize LXD storage](https://discourse.ubuntu.com/t/resize-lxd-storage/32569)| -| 2 | howto/manage/web-dashboard | [Use the web dashboard](https://discourse.ubuntu.com/t/web-dashboard/20871)| -| 2 | howto/application/landing | [Manage applications](https://discourse.ubuntu.com/t/manage-applications/24333) | -| 3 | howto/application/create | [Create an application](https://discourse.ubuntu.com/t/create-an-application/24198)| -| 3 | howto/application/stream | [Stream an application](https://discourse.ubuntu.com/t/how-to-stream-applications/42688)| -| 3 | howto/application/wait | [Wait for an application](https://discourse.ubuntu.com/t/wait-for-an-application/24202)| -| 3 | howto/application/list | [List applications](https://discourse.ubuntu.com/t/list-applications/24200)| -| 3 | howto/application/userdata | [Pass custom data](https://discourse.ubuntu.com/t/how-to-pass-custom-data-to-an-application/30368)| -| 3 | howto/application/test | [Test your application](https://discourse.ubuntu.com/t/usecase-application-testing/17775)| -| 3 | howto/application/update | [Update an application](https://discourse.ubuntu.com/t/update-an-application/24201)| -| 3 | howto/application/delete | [Delete an application](https://discourse.ubuntu.com/t/delete-an-application/24199)| -| 3 | howto/application/extend | [Extend an application](https://discourse.ubuntu.com/t/extand-an-application/28554)| -| 2 | howto/application/virtual-devices | [Create a virtual device](https://discourse.ubuntu.com/t/virtual-devices/19069)| -| 2 | howto/aar/landing | [Manage AAR](https://discourse.ubuntu.com/t/manage-aar/36807)| -| 3 | howto/aar/deploy | [Deploy an AAR](https://discourse.ubuntu.com/t/installation-application-registry/17749)| -| 3 | howto/aar/configure | [Configure an AAR](https://discourse.ubuntu.com/t/configure-an-aar/24319)| -| 3 | howto/aar/revoke | [Revoke an AAR client](https://discourse.ubuntu.com/t/revoke-an-aar-client/24320)| -| 2 | howto/port/landing | [Port Android apps](https://discourse.ubuntu.com/t/port-android-apps/17776)| -| 3 | howto/port/permissions | [Grant permissions](https://discourse.ubuntu.com/t/grant-runtime-permissions/26054)| -| 3 | howto/port/architecture | [Choose APK architecture](https://discourse.ubuntu.com/t/choose-apk-architecture/26055)| -| 3 | howto/port/obb-files | [Port APKs with OBB files](https://discourse.ubuntu.com/t/port-apks-with-obb-files/26056)| -| 3 | howto/port/configure-watchdog | [Configure the watchdog](https://discourse.ubuntu.com/t/configure-the-watchdog/26057)| -| 3 | howto/port/install-system-app | [Install APK as a system app](https://discourse.ubuntu.com/t/install-an-apk-as-a-system-app/27086)| -| 2 | howto/instance/landing | [Manage instances](https://discourse.ubuntu.com/t/24335) | -| 3 | howto/instance/create | [Create an instance](https://discourse.ubuntu.com/t/24327)| -| 3 | howto/instance/start | [Start an instance](https://discourse.ubuntu.com/t/33924)| -| 3 | howto/instance/wait | [Wait for an instance](https://discourse.ubuntu.com/t/24330)| -| 3 | howto/instance/access | [Access an instance](https://discourse.ubuntu.com/t/17772)| -| 3 | howto/instance/list | [List instances](https://discourse.ubuntu.com/t/24328)| -| 3 | howto/instance/geographic-location | [Configure geographic location](https://discourse.ubuntu.com/t/17782)| -| 3 | howto/instance/logs | [View the instance logs](https://discourse.ubuntu.com/t/24329)| -| 3 | howto/instance/stop | [Stop an instance](https://discourse.ubuntu.com/t/33925)| -| 3 | howto/instance/backup-and-restore | [Back up and restore application data](https://discourse.ubuntu.com/t/24183)| -| 3 | howto/instance/delete | [Delete an instance](https://discourse.ubuntu.com/t/24325)| -| 3 | howto/instance/expose-services | [Expose services](https://discourse.ubuntu.com/t/24326)| -| 2 | howto/addons/landing | [Use addons](https://discourse.ubuntu.com/t/managing-addons/17759)| -| 3 | howto/addons/create | [Create addons](https://discourse.ubuntu.com/t/create-an-addon/40632)| -| 3 | howto/addons/enable-globally | [Enable globally](https://discourse.ubuntu.com/t/enable-an-addon-globally/25285)| -| 3 | howto/addons/update | [Update addons](https://discourse.ubuntu.com/t/update-addons/25286)| -| 3 | howto/addons/migrate | [Migrate from previous versions](https://discourse.ubuntu.com/t/migrate-from-previous-addon-versions/25287)| -| 3 | howto/addons/install-tools | [Example: Install tools](https://discourse.ubuntu.com/t/example-install-tools/25288)| -| 3 | howto/addons/backup-and-restore | [Example: Back up data](https://discourse.ubuntu.com/t/example-back-up-data/25289)| -| 3 | howto/addons/customise-android | [Example: Customise Android](https://discourse.ubuntu.com/t/example-customise-android/25290)| -| 3 | howto/addons/emulate-platforms | [Example: Emulate platforms](https://discourse.ubuntu.com/t/example-emulate-platforms/25291)| -| 2 | howto/stream/landing | [Implement streaming](https://discourse.ubuntu.com/t/implement-streaming/24332) | -| 3 | howto/stream/access | [Access the stream gateway](https://discourse.ubuntu.com/t/managing-stream-gateway-access/17784) | -| 3 | howto/stream/oob-data | [Exchange OOB data](https://discourse.ubuntu.com/t/exchange-out-of-band-data/21834)| -| 3 | howto/stream/client-side-keyboard | [Use a client-side keyboard](https://discourse.ubuntu.com/t/integrate-a-client-side-virtual-keyboard/23643)| -| 2 | howto/cluster/landing | [Manage the cluster](https://discourse.ubuntu.com/t/manage-cluster-nodes/24334) | -| 3 | howto/cluster/configure-nodes | [Configure cluster nodes](https://discourse.ubuntu.com/t/configure-cluster-nodes/28716) | -| 3 | howto/cluster/scale-up | [Scale up a LXD cluster](https://discourse.ubuntu.com/t/scale-up-a-lxd-cluster/24322)| -| 3 | howto/cluster/scale-down | [Scale down a LXD cluster](https://discourse.ubuntu.com/t/scale-down-a-lxd-cluster/24323)| -| 2 | howto/anbox/landing | [Work with the Anbox runtime](https://discourse.ubuntu.com/t/how-to-work-with-the-anbox-runtime/33098) | -| 3 | howto/anbox/develop-platform | [Develop a platform plugin](https://discourse.ubuntu.com/t/how-to-develop-a-platform-plugin/33099) | -| 3 | howto/anbox/develop-addon | [Develop and test addons](https://discourse.ubuntu.com/t/develop-and-test-addons-in-development-mode/36914) | -| 2 | howto/android/landing | [Work with Android](https://discourse.ubuntu.com/t/how-to-work-with-android-in-anbox-cloud/42428) | -| 3 | howto/android/graphics-debugging-with-renderdoc | [Graphics debugging with Renderdoc](https://discourse.ubuntu.com/t/how-to-debug-graphics-with-renderdoc/42427) | -| 3 | howto/android/custom_vhal | [Replace the Anbox VHAL](https://discourse.ubuntu.com/t/replace-the-anbox-vhal/45070) | -| 2 | howto/troubleshoot/landing | [Troubleshoot Anbox Cloud](https://discourse.ubuntu.com/t/how-to-troubleshoot-anbox-cloud/17837)| -| 3 | howto/troubleshoot/initial-setup | [Troubleshoot initial setup](https://discourse.ubuntu.com/t/troubleshoot-issues-with-initial-setup/35704)| -| 3 | howto/troubleshoot/logs | [View logs](https://discourse.ubuntu.com/t/managing-logs/17771)| -| 3 | howto/troubleshoot/application-creation | [Troubleshoot application creation](https://discourse.ubuntu.com/t/troubleshoot-issues-with-application-creation/35702)| -| 3 | howto/troubleshoot/instance-failures | [Troubleshoot instance failures](https://discourse.ubuntu.com/t/35703)| -| 3 | howto/troubleshoot/lxd-cluster | [Troubleshoot LXD cluster](https://discourse.ubuntu.com/t/troubleshoot-issues-with-lxd-clustering/35705)| -| 3 | howto/troubleshoot/dashboard-issues | [Troubleshoot dashboard issues](https://discourse.ubuntu.com/t/36105) -| 3 | howto/troubleshoot/streaming-issues | [Troubleshoot streaming issues](https://discourse.ubuntu.com/t/how-to-debug-streaming-issues/31341)| -| 2 | howto/monitor/landing | [Monitor Anbox Cloud](https://discourse.ubuntu.com/t/monitor-anbox-cloud/24338) | -| 0 | | | -| 1 | reference/landing | [Reference](https://discourse.ubuntu.com/t/reference/28828) | -| 2 | reference/releases-versions | [Releases and versions](https://discourse.ubuntu.com/t/releases-and-versions/37993) | -| 3 | reference/roadmap | [Release roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359)| -| 3 | reference/release-notes/release-notes | [Release notes](https://discourse.ubuntu.com/t/release-notes/17842)| -| 3 | reference/supported-versions | [Supported versions](https://discourse.ubuntu.com/t/supported-versions/21046) | -| 3 | reference/component-versions | [Component versions](https://discourse.ubuntu.com/t/component-versions/21413)| -| 2 | reference/requirements | [Requirements](https://discourse.ubuntu.com/t/installation-requirements/17734) | -| 2 | reference/appliance-command-reference/landing | [Appliance command reference](https://discourse.ubuntu.com/t/39525)| -| 2 | reference/amc-command-reference/landing | [AMC command reference](https://discourse.ubuntu.com/t/40797) | -| 2 | reference/provided-images | [Provided images](https://discourse.ubuntu.com/t/provided-images/24185)| -| 2 | reference/supported-rendering-resources | [Supported rendering resources](https://discourse.ubuntu.com/t/supported-rendering-resources/37322) | -| 2 | reference/supported-codecs | [Supported codecs](https://discourse.ubuntu.com/t/37323)| -| 2 | reference/android-features | [Supported Android features](https://discourse.ubuntu.com/t/supported-android-features/28825)| -| 2 | reference/anbox-features | [Supported Anbox features](https://discourse.ubuntu.com/t/supported-features-aosp-vs-aaos/42520)| -| 2 | reference/ams-configuration | [AMS configuration](https://discourse.ubuntu.com/t/ams-configuration/20872)| -| 2 | reference/application-manifest | [Application manifest](https://discourse.ubuntu.com/t/application-manifest/24197)| -| 2 | reference/api-reference | [APIs](https://discourse.ubuntu.com/t/api-reference/24339) | -| 3 | reference/ams-http-api | [AMS HTTP API](https://canonical.github.io/anbox-cloud.github.com/latest/ams/)| -| 3 | reference/anbox-https-api | [Anbox HTTP API](https://discourse.ubuntu.com/t/anbox-http-api-reference/17819)| -| 3 | reference/anbox-stream-gateway | [Stream Gateway API](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway/)| -| 3 | reference/anbox-platform-sdk-api | [Anbox Platform SDK API](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/)| -| 2 | reference/sdks | [Anbox Cloud SDKs](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844)| -| 2 | reference/network-ports | [Network ports](https://discourse.ubuntu.com/t/network-ports/33650)| -| 2 | reference/addon-manifest | [Addon manifest](https://discourse.ubuntu.com/t/addons/25293)| -| 2 | reference/hooks | [Hooks](https://discourse.ubuntu.com/t/hooks/28555)| -| 2 | reference/webrtc-streamer | [WebRTC streamer](https://discourse.ubuntu.com/t/webrtc-streamer/30195)| -| 2 | reference/prometheus | [Prometheus metrics](https://discourse.ubuntu.com/t/prometheus-metrics/19521)| -| 2 | reference/perf-benchmarks | [Performance benchmarks](https://discourse.ubuntu.com/t/performance-benchmarks/24709)| -| 2 | reference/deprecation-notices | [Deprecations](https://discourse.ubuntu.com/t/deprecation-notices/45073)| -| 2 | reference/license-information | [License information](https://discourse.ubuntu.com/t/license-information/36649) | -| 2 | reference/glossary | [Glossary](https://discourse.ubuntu.com/t/glossary/26204)| -| 0 | | | -| 1 | explanation/landing | [Explanation](https://discourse.ubuntu.com/t/explanation/28829) | -| 2 | explanation/anbox-cloud | [Anbox Cloud](https://discourse.ubuntu.com/t/anbox-cloud-overview/17802) | -| 2 | explanation/rendering-architecture | [Rendering architecture](https://discourse.ubuntu.com/t/about-rendering-architecture/35129) | -| 2 | explanation/aaos | [AAOS](https://discourse.ubuntu.com/t/android-automotive-os-aaos/44274)| -| 2 | explanation/security | [Security](https://discourse.ubuntu.com/t/about-security/31217)| -| 2 | explanation/ams | [AMS](https://discourse.ubuntu.com/t/about-ams/24321)| -| 2 | explanation/aar | [AAR](https://discourse.ubuntu.com/t/application-registry/17761)| -| 2 | explanation/web-dashboard | [Dashboard](https://discourse.ubuntu.com/t/anbox-cloud-web-dashboard/41847) -| 2 | explanation/applications | [Applications](https://discourse.ubuntu.com/t/managing-applications/17760)| -| 3 | explanation/resources | [Resources and resource presets](https://discourse.ubuntu.com/t/24960)| -| 2 | explanation/addons | [Addons](https://discourse.ubuntu.com/t/addons/38727)| -| 2 | explanation/application-streaming | [Application streaming](https://discourse.ubuntu.com/t/streaming-android-applications/17769)| -| 2 | explanation/instances | [Instances](https://discourse.ubuntu.com/t/17763)| -| 2 | explanation/images | [Images](https://discourse.ubuntu.com/t/images/43914) | -| 2 | explanation/custom-images | [Custom images](https://discourse.ubuntu.com/t/custom-images/45071) | -| 2 | explanation/nodes | [Nodes](https://discourse.ubuntu.com/t/nodes/43915) | -| 2 | explanation/platforms | [Platforms](https://discourse.ubuntu.com/t/anbox-platforms/18733)| -| 2 | explanation/gpus-instances | [GPUs and instances](https://discourse.ubuntu.com/t/17768)| -| 2 | explanation/clustering | [Clustering](https://discourse.ubuntu.com/t/capacity-planning/17765)| -| 2 | explanation/performance | [Performance](https://discourse.ubuntu.com/t/about-performance/29416) | -| 2 | explanation/capacity-planning | [Capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) | -| 2 | explanation/production | [Production planning](https://discourse.ubuntu.com/t/about-production-planning/34648) | -| 0 | | | -| 1 | |[Documentation feedback](https://forms.gle/6yzgLbwN8rVYSdvG9)| -| 0 | | | -| | reference/release-notes/1.22.1 | [Release notes-Anbox Cloud 1.22.1](https://discourse.ubuntu.com/t/45752)| -| | reference/release-notes/1.22.0 | [Release notes-Anbox Cloud 1.22.0](https://discourse.ubuntu.com/t/45074)| -| | reference/release-notes/1.21.2 | [Release notes-Anbox Cloud 1.21.2](https://discourse.ubuntu.com/t/44276)| -| | reference/release-notes/1.21.1 | [Release notes-Anbox Cloud 1.21.1](https://discourse.ubuntu.com/t/43279)| -| | reference/release-notes/1.21.0 | [Release notes-Anbox Cloud 1.21.0](https://discourse.ubuntu.com/t/42429)| -| | reference/release-notes/1.20.2 | [Release notes-Anbox Cloud 1.20.2](https://discourse.ubuntu.com/t/41686)| -| | reference/release-notes/1.20.1 | [Release notes-Anbox Cloud 1.20.1](https://discourse.ubuntu.com/t/40988)| -| | reference/release-notes/1.20.0 | [Release notes-Anbox Cloud 1.20.0](https://discourse.ubuntu.com/t/40281)| -| | reference/release-notes/1.19.2 | [Release notes-Anbox Cloud 1.19.2](https://discourse.ubuntu.com/t/39311)| -| | reference/release-notes/1.19.1 | [Release notes-Anbox Cloud 1.19.1](https://discourse.ubuntu.com/t/38595)| -| | reference/release-notes/1.19.0-fix1 | [Hotfix release announcement](https://discourse.ubuntu.com/t/38250)| -| | reference/release-notes/1.19.0 | [Release notes-Anbox Cloud 1.19.0](https://discourse.ubuntu.com/t/37849)| -| | reference/release-notes/1.18.2 | [Release notes-Anbox Cloud 1.18.2](https://discourse.ubuntu.com/t/36916)| -| | reference/release-notes/1.18.1 | [Release notes-Anbox Cloud 1.18.1](https://discourse.ubuntu.com/t/36309)| -| | reference/release-notes/1.18.0 | [Release notes-Anbox Cloud 1.18.0](https://discourse.ubuntu.com/t/35812)| -| | reference/release-notes/1.17.2 | [Release notes-Anbox Cloud 1.17.2](https://discourse.ubuntu.com/t/35195)| -| | reference/release-notes/1.17.1 | [Release notes-Anbox Cloud 1.17.1](https://discourse.ubuntu.com/t/34573)| -| | reference/release-notes/1.17.0 | [Release notes-Anbox Cloud 1.17.0](https://discourse.ubuntu.com/t/33927)| -| | reference/release-notes/1.16.4 | [Release notes-Anbox Cloud 1.16.4](https://discourse.ubuntu.com/t/33437)| -| | reference/release-notes/1.16.3 | [Release notes-Anbox Cloud 1.16.3](https://discourse.ubuntu.com/t/33261)| -| | reference/release-notes/1.16.2 | [Release notes-Anbox Cloud 1.16.2](https://discourse.ubuntu.com/t/33161)| -| | reference/release-notes/1.16.1 | [Release notes-Anbox Cloud 1.16.1](https://discourse.ubuntu.com/t/32733)| -| | reference/release-notes/1.16.0 | [Release notes-Anbox Cloud 1.16.0](https://discourse.ubuntu.com/t/32264)| -| | reference/release-notes/1.15.3 | [Release notes-Anbox Cloud 1.15.3](https://discourse.ubuntu.com/t/31616)| -| | reference/release-notes/1.15.2 | [Release notes-Anbox Cloud 1.15.2](https://discourse.ubuntu.com/t/31322)| -| | reference/release-notes/1.15.1 | [Release notes-Anbox Cloud 1.15.1](https://discourse.ubuntu.com/t/30585)| -| | reference/release-notes/1.15.0 | [Release notes-Anbox Cloud 1.15.0](https://discourse.ubuntu.com/t/30196)| -| | reference/release-notes/1.14.2 | [Release notes-Anbox Cloud 1.14.2](https://discourse.ubuntu.com/t/29553)| -| | reference/release-notes/1.14.1 | [Release notes-Anbox Cloud 1.14.1](https://discourse.ubuntu.com/t/28952)| -| | reference/release-notes/1.14.0 | [Release notes-Anbox Cloud 1.14.0](https://discourse.ubuntu.com/t/28557)| -| | reference/release-notes/1.13.2 | [Release notes-Anbox Cloud 1.13.2](https://discourse.ubuntu.com/t/27701)| -| | reference/release-notes/1.13.1 | [Release notes-Anbox Cloud 1.13.1](https://discourse.ubuntu.com/t/27254)| -| | reference/release-notes/1.13.0 | [Release notes-Anbox Cloud 1.13.0](https://discourse.ubuntu.com/t/26857)| -| | reference/release-notes/1.12.5 | [Release notes-Anbox Cloud 1.12.5](https://discourse.ubuntu.com/t/26380)| -| | reference/release-notes/1.12.4 | [Release notes-Anbox Cloud 1.12.4](https://discourse.ubuntu.com/t/26263)| -| | reference/release-notes/1.12.3 | [Release notes-Anbox Cloud 1.12.3](https://discourse.ubuntu.com/t/26252)| -| | reference/release-notes/1.12.2 | [Release notes-Anbox Cloud 1.12.2](https://discourse.ubuntu.com/t/25819)| -| | reference/release-notes/1.12.1 | [Release notes-Anbox Cloud 1.12.1](https://discourse.ubuntu.com/t/25542)| -| | reference/release-notes/1.12.0 | [Release notes-Anbox Cloud 1.12.0](https://discourse.ubuntu.com/t/25295)| -| | reference/release-notes/1.11.5 | [Release notes-Anbox Cloud 1.11.5](https://discourse.ubuntu.com/t/26739)| -| | reference/release-notes/1.11.4 | [Release notes-Anbox Cloud 1.11.4](https://discourse.ubuntu.com/t/25018)| -| | reference/release-notes/1.11.3 | [Release notes-Anbox Cloud 1.11.3](https://discourse.ubuntu.com/t/24705)| -| | reference/release-notes/1.11.2 | [Release notes-Anbox Cloud 1.11.2](https://discourse.ubuntu.com/t/24293)| -| | reference/release-notes/1.11.1 | [Release notes-Anbox Cloud 1.11.1](https://discourse.ubuntu.com/t/23772)| -| | reference/release-notes/1.11.0 | [Release notes-Anbox Cloud 1.11.0](https://discourse.ubuntu.com/t/23590)| -| | reference/release-notes/1.10.3 | [Release notes-Anbox Cloud 1.10.3](https://discourse.ubuntu.com/t/23267)| -| | reference/release-notes/1.10.2 | [Release notes-Anbox Cloud 1.10.2](https://discourse.ubuntu.com/t/22692)| -| | reference/release-notes/1.10.1 | [Release notes-Anbox Cloud 1.10.1](https://discourse.ubuntu.com/t/22280)| -| | reference/release-notes/1.10.0 | [Release notes-Anbox Cloud 1.10.0](https://discourse.ubuntu.com/t/22205)| -| | reference/release-notes/1.9.5 | [Release notes-Anbox Cloud 1.9.5](https://discourse.ubuntu.com/t/22259)| -| | reference/release-notes/1.9.4 | [Release notes-Anbox Cloud 1.9.4](https://discourse.ubuntu.com/t/22148)| -| | reference/release-notes/1.9.3 | [Release notes-Anbox Cloud 1.9.3](https://discourse.ubuntu.com/t/21795)| -| | reference/release-notes/1.9.2 | [Release notes-Anbox Cloud 1.9.2](https://discourse.ubuntu.com/t/21420)| -| | reference/release-notes/1.9.1 | [Release notes-Anbox Cloud 1.9.1](https://discourse.ubuntu.com/t/21232)| -| | reference/release-notes/1.9.0 | [Release notes-Anbox Cloud 1.9.0](https://discourse.ubuntu.com/t/20870)| -| | reference/release-notes/1.8.3 | [Release notes-Anbox Cloud 1.8.3](https://discourse.ubuntu.com/t/20435)| -| | reference/release-notes/1.8.2 | [Release notes-Anbox Cloud 1.8.2](https://discourse.ubuntu.com/t/19951)| -| | reference/release-notes/1.8.1 | [Release notes-Anbox Cloud 1.8.1](https://discourse.ubuntu.com/t/19319)| -| | reference/release-notes/1.8.0 | [Release notes-Anbox Cloud 1.8.0](https://discourse.ubuntu.com/t/19200)| -| | reference/release-notes/1.7.4 | [Release notes-Anbox Cloud 1.7.4](https://discourse.ubuntu.com/t/18812)| -| | reference/release-notes/1.7.3 | [Release notes-Anbox Cloud 1.7.3](https://discourse.ubuntu.com/t/18458)| -| | reference/release-notes/1.7.2 | [Release notes-Anbox Cloud 1.7.2](https://discourse.ubuntu.com/t/18265)| -| | reference/release-notes/1.7.1 | [Release notes-Anbox Cloud 1.7.1](https://discourse.ubuntu.com/t/17977)| -| | reference/appliance-command-reference/ams | [Appliance command reference - ams](https://discourse.ubuntu.com/t/39517)| -| | reference/appliance-command-reference/dashboard | [Appliance command reference - dashboard](https://discourse.ubuntu.com/t/39520)| -| | reference/appliance-command-reference/destroy | [Appliance command reference - destroy](https://discourse.ubuntu.com/t/39521)| -| | reference/appliance-command-reference/gateway | [Appliance command reference - gateway](https://discourse.ubuntu.com/t/39522)| -| | reference/appliance-command-reference/help | [Appliance command reference - help](https://discourse.ubuntu.com/t/39523)| -| | reference/appliance-command-reference/init | [Appliance command reference - init](https://discourse.ubuntu.com/t/39524)| -| | reference/appliance-command-reference/status | [Appliance command reference - status](https://discourse.ubuntu.com/t/39527)| -| | reference/appliance-command-reference/upgrade | [Appliance command reference - upgrade](https://discourse.ubuntu.com/t/39528)| -| | reference/amc-command-reference/addon | [AMC command reference - addon](https://discourse.ubuntu.com/t/40775) | -| | reference/amc-command-reference/application | [AMC command reference - application](https://discourse.ubuntu.com/t/40776) | -| | reference/amc-command-reference/benchmark | [AMC command reference - benchmark](https://discourse.ubuntu.com/t/40777) | -| | reference/amc-command-reference/completion | [AMC command reference - completion](https://discourse.ubuntu.com/t/40778) | -| | reference/amc-command-reference/config | [AMC command reference - config](https://discourse.ubuntu.com/t/40779) | -| | reference/amc-command-reference/delete | [AMC command reference - delete](https://discourse.ubuntu.com/t/40780) | -| | reference/amc-command-reference/exec | [AMC command reference - exec](https://discourse.ubuntu.com/t/40781) | -| | reference/amc-command-reference/help | [AMC command reference - help](https://discourse.ubuntu.com/t/40782) | -| | reference/amc-command-reference/image | [AMC command reference - image](https://discourse.ubuntu.com/t/40783) | -| | reference/amc-command-reference/info | [AMC command reference - info](https://discourse.ubuntu.com/t/40784) | -| | reference/amc-command-reference/init | [AMC command reference - init](https://discourse.ubuntu.com/t/40785) | -| | reference/amc-command-reference/launch | [AMC command reference - launch](https://discourse.ubuntu.com/t/40786) | -| | reference/amc-command-reference/list | [AMC command reference - list](https://discourse.ubuntu.com/t/40787) | -| | reference/amc-command-reference/logs | [AMC command reference - logs](https://discourse.ubuntu.com/t/40788) | -| | reference/amc-command-reference/node | [AMC command reference - node](https://discourse.ubuntu.com/t/40789) | -| | reference/amc-command-reference/remote | [AMC command reference - remote](https://discourse.ubuntu.com/t/40790) | -| | reference/amc-command-reference/shell | [AMC command reference - shell](https://discourse.ubuntu.com/t/40791) | -| | reference/amc-command-reference/show-log | [AMC command reference - show-log](https://discourse.ubuntu.com/t/40792) | -| | reference/amc-command-reference/show | [AMC command reference - show](https://discourse.ubuntu.com/t/40793) | -| | reference/amc-command-reference/start | [AMC command reference - start](https://discourse.ubuntu.com/t/40794) | -| | reference/amc-command-reference/stop | [AMC command reference - stop](https://discourse.ubuntu.com/t/40795) | -| | reference/amc-command-reference/wait | [AMC command reference - wait](https://discourse.ubuntu.com/t/40796) | -[/details] +For official support requirements, you can get support through [Ubuntu Pro](https://ubuntu.com/support). -## Redirects -[details=Mapping table] -| Path | Location | -| ---- | -------- | -| /docs/tut/creating-addon | /docs/tutorial/creating-addon | -| /docs/tut/getting-started-dashboard | /docs/tutorial/getting-started-dashboard | -| /docs/tut/getting-started | /docs/tutorial/getting-started | -| /docs/tut/installing-appliance | /docs/tutorial/installing-appliance | -| /docs/tut/landing | /docs/tutorial/landing | -| /docs/tut/stream-client | /docs/tutorial/stream-client | -| /docs/ref/addon-manifest | /docs/reference/addon-manifest | -| /docs/ref/ams-configuration | /docs/reference/ams-configuration | -| /docs/ref/anbox-https-api | /docs/reference/anbox-https-api | -| /docs/ref/android-features | /docs/reference/android-features | -| /docs/ref/api-reference | /docs/reference/api-reference | -| /docs/ref/application-manifest | /docs/reference/application-manifest | -| /docs/ref/component-versions | /docs/reference/component-versions | -| /docs/ref/glossary | /docs/reference/glossary | -| /docs/ref/hooks | /docs/reference/hooks | -| /docs/ref/landing | /docs/reference/landing | -| /docs/ref/license-information | /docs/reference/license-information | -| /docs/ref/network-ports | /docs/reference/network-ports | -| /docs/ref/perf-benchmarks | /docs/reference/perf-benchmarks | -| /docs/ref/prometheus | /docs/reference/prometheus | -| /docs/ref/provided-images | /docs/reference/provided-images | -| /docs/ref/releases-versions | /docs/reference/releases-version | -| /docs/ref/requirements | /docs/reference/requirements | -| /docs/ref/roadmap | /docs/reference/roadmap | -| /docs/ref/sdks | /docs/reference/sdks | -| /docs/ref/supported-codecs | /docs/reference/supported-codecs | -| /docs/ref/supported-rendering-resources | /docs/reference/supported-rendering-resources | -| /docs/ref/supported-versions | /docs/reference/supported-versions | -| /docs/ref/webrtc-streamer | /docs/reference/webrtc-streamer | -| /docs/ref/release-notes | /docs/reference/release-notes | -| /docs/ref/appliance-command-reference/landing | /docs/reference/appliance-command-reference/landing| -| /docs/ref/appliance-command-reference/ams | /docs/reference/appliance-command-reference/ams| -| /docs/ref/appliance-command-reference/cluster | /docs/reference/appliance-command-reference/cluster| -| /docs/ref/appliance-command-reference/dashboard | /docs/reference/appliance-command-reference/dashboard| -| /docs/ref/appliance-command-reference/destroy | /docs/reference/appliance-command-reference/destroy| -| /docs/ref/appliance-command-reference/gateway | /docs/reference/appliance-command-reference/gateway| -| /docs/ref/appliance-command-reference/help | /docs/reference/appliance-command-reference/help| -| /docs/ref/appliance-command-reference/init | /docs/reference/appliance-command-reference/init| -| /docs/ref/appliance-command-reference/landing | /docs/reference/appliance-command-reference/landing| -| /docs/ref/appliance-command-reference/status | /docs/reference/appliance-command-reference/status| -| /docs/ref/appliance-command-reference/upgrade | /docs/reference/appliance-command-reference/upgrade| -| /docs/ref/amc-command-reference/landing | /docs/reference/amc-command-reference/landing| -| /docs/ref/amc-command-reference/addon | /docs/reference/amc-command-reference/addon| -| /docs/ref/amc-command-reference/application | /docs/reference/amc-command-reference/application| -| /docs/ref/amc-command-reference/benchmark | /docs/reference/amc-command-reference/benchmark| -| /docs/ref/amc-command-reference/completion | /docs/reference/amc-command-reference/completion| -| /docs/ref/amc-command-reference/config | /docs/reference/amc-command-reference/config| -| /docs/ref/amc-command-reference/delete | /docs/reference/amc-command-reference/delete| -| /docs/ref/amc-command-reference/exec | /docs/reference/amc-command-reference/exec| -| /docs/ref/amc-command-reference/help | /docs/reference/amc-command-reference/help| -| /docs/ref/amc-command-reference/image | /docs/reference/amc-command-reference/image| -| /docs/ref/amc-command-reference/info | /docs/reference/amc-command-reference/info| -| /docs/ref/amc-command-reference/init | /docs/reference/amc-command-reference/init| -| /docs/ref/amc-command-reference/launch | /docs/reference/amc-command-reference/launch| -| /docs/ref/amc-command-reference/list | /docs/reference/amc-command-reference/list| -| /docs/ref/amc-command-reference/logs | /docs/reference/amc-command-reference/logs| -| /docs/ref/amc-command-reference/node | /docs/reference/amc-command-reference/node| -| /docs/ref/amc-command-reference/remote | /docs/reference/amc-command-reference/remote| -| /docs/ref/amc-command-reference/shell | /docs/reference/amc-command-reference/shell| -| /docs/ref/amc-command-reference/show-log | /docs/reference/amc-command-reference/show-log| -| /docs/ref/amc-command-reference/show | /docs/reference/amc-command-reference/show| -| /docs/ref/amc-command-reference/start | /docs/reference/amc-command-reference/start| -| /docs/ref/amc-command-reference/stop | /docs/reference/amc-command-reference/stop| -| /docs/ref/amc-command-reference/wait | /docs/reference/amc-command-reference/wait| -| /docs/exp/landing | /docs/explanation/landing | -| /docs/exp/aar | /docs/explanation/aar | -| /docs/exp/addons | /docs/explanation/addons | -| /docs/exp/ams | /docs/explanation/ams | -| /docs/exp/anbox-cloud | /docs/explanation/anbox-cloud | -| /docs/exp/application-streaming | /docs/explanation/application-streaming | -| /docs/exp/applications | /docs/explanation/applications | -| /docs/exp/capacity-planning | /docs/explanation/capacity-planning | -| /docs/exp/clustering | /docs/explanation/clustering | -| /docs/exp/gpus-instances | /docs/explanation/gpus-instances | -| /docs/exp/instances | /docs/explanation/instances | -| /docs/exp/performance | /docs/explanation/performance | -| /docs/exp/platforms | /docs/explanation/platforms | -| /docs/exp/production | /docs/explanation/production | -| /docs/exp/rendering-architecture | /docs/explanation/rendering-architecture | -| /docs/exp/resources | /docs/explanation/resources | -| /docs/exp/security | /docs/explanation/security | -| /docs/manage/container-access | /docs/howto/instance/access | -| /docs/howto/container/view-log | /docs/howto/instance/logs | -| /docs/usage/usecase-container-configuration | /docs/howto/instance/geographic-location | -| /docs/howto/containers/backup-and-restore | /docs/howto/instance/backup-and-restore | -| /docs/howto/stream/web-client | /docs/tut/stream-client | -| /docs/howto/troubleshoot/collect-info | /docs/howto/troubleshoot/landing | -| /docs/manage/managing-containers | /docs/exp/instances | -| /docs/exp/gpu-support | /docs/explanation/gpus-instances | -| /docs/howto/container/launch | /docs/howto/instance/create | -| /docs/howto/stream/debug | /docs/howto/troubleshoot/streaming-issues | -| /docs/howto/manage/logs | /docs/howto/troubleshoot/logs | -| /docs/ref/platforms | /docs/explanation/platforms | -| /docs/ref/instance-types | /docs/reference/application-manifest | -| /docs/ref/supported-video-codecs | /docs/reference/supported-codecs | -| /docs/howto/addons/best-practices | /docs/explanation/addons | -| /docs/ref/addons | /docs/reference/addon-manifest | -| /docs/howto/manage/manage-appliance | /docs/reference/appliance-command-reference/landing | -| /docs/exp/containers | /docs/explanation/instances | -| /docs/howto/container | /docs/howto/instance | -| /docs/howto/troubleshoot/container-failures | /docs/howto/troubleshoot/instance-failures | -| /docs/howto/container/access | /docs/howto/instance/access | -| /docs/howto/container/backup-and-restore | /docs/howto/instance/backup-and-restore | -| /docs/howto/container/create | /docs/howto/instance/create | -| /docs/howto/container/delete | /docs/howto/instance/delete | -| /docs/howto/container/expose-service | /docs/howto/instance/expose-service | -| /docs/howto/container/geographic-location | /docs/howto/instance/geographic-location | -| /docs/howto/container/landing | /docs/howto/instance/landing | -| /docs/howto/container/list | /docs/howto/instance/list | -| /docs/howto/container/logs | /docs/howto/instance/logs | -| /docs/howto/container/start | /docs/howto/instance/start | -| /docs/howto/container/stop | /docs/howto/instance/stop | -| /docs/howto/container/wait | /docs/howto/instance/wait | -| /docs/howto/application/resources | /docs/explanation/resources | -[/details] +Thinking about using Anbox Cloud for your next project? [Get in touch!](https://anbox-cloud.io/contact-us) + +```{toctree} +:hidden: +tutorial/landing +howto/landing +explanation/landing +reference/landing +contribute/landing +``` diff --git a/init.sh b/init.sh new file mode 100755 index 00000000..99b093a1 --- /dev/null +++ b/init.sh @@ -0,0 +1,51 @@ +#!/bin/bash + +# Generate a unique directory name based on timestamp +timestamp=$(date +%Y%m%d%H%M%S) +temp_directory="temp-starter-pack-$timestamp" + +# Ask the user for the installation directory +read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_directory + +# Clone the starter pack repository to the temporary directory +echo "Cloning the starter pack repository..." +git clone --depth 1 https://github.com/canonical/sphinx-docs-starter-pack "$temp_directory" +rm -rf "$temp_directory/.git" + +# Update file contents for the install directory +echo "Updating working directory in workflow files..." +sed -i "s|working-directory:\s*'\.'|working-directory: '$install_directory'|g" "$temp_directory/.github/workflows"/* +echo "Updating .readthedocs.yaml configuration..." +sed -i "s|-\s\s*python3\s\s*build_requirements\.py|- cd '$install_directory' \&\& python3 build_requirements.py|g" "$temp_directory/.readthedocs.yaml" +sed -i "s|configuration:\s*conf\.py|configuration: $install_directory/conf.py|g" "$temp_directory/.readthedocs.yaml" +sed -i "s|requirements:\s*\.sphinx/requirements\.txt|requirements: $install_directory/.sphinx/requirements.txt|g" "$temp_directory/.readthedocs.yaml" + +# Create the specified installation directory if it doesn't exist +if [ ! -d "$install_directory" ]; then + echo "Creating the installation directory: $install_directory" + mkdir -p "$install_directory" +fi + +# Copy the contents of the starter pack repository to the installation directory +echo "Copying contents to the installation directory..." +cp -R "$temp_directory"/* "$temp_directory"/.??* "$install_directory" + +# Move workflow files and configuration +if [ "$install_directory" != "." ]; then + echo "Moving workflow files and configuration..." + if [ ! -d .github/workflows ]; then + mkdir -p .github/workflows + fi + mv "$install_directory/.github/workflows"/* .github/workflows + if [ ! -f .wokeignore ]; then + ln -s "$install_directory/.wokeignore" + else + echo "ACTION REQUIRED: Found a .wokeignore file in the root directory. Include the contents from $install_directory/.wokeignore in this file!" + fi +fi + +# Clean up +echo "Cleaning up..." +rm -rf "$temp_directory" + +echo "Setup completed!" diff --git a/pa11y.json b/pa11y.json new file mode 100644 index 00000000..8df0cb9c --- /dev/null +++ b/pa11y.json @@ -0,0 +1,9 @@ +{ + "chromeLaunchConfig": { + "args": [ + "--no-sandbox" + ] + }, + "reporter": "cli", + "standard": "WCAG2AA" +} \ No newline at end of file diff --git a/publish-pr.sh b/publish-pr.sh deleted file mode 100755 index dc361cf5..00000000 --- a/publish-pr.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/sh - -python3 scripts/publish-pr.py $1 diff --git a/publish.sh b/publish.sh deleted file mode 100755 index c74d13da..00000000 --- a/publish.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/sh - -python3 scripts/publish.py $1 diff --git a/reference/addon-manifest.md b/reference/addon-manifest.md index 1503ff7c..beec7556 100644 --- a/reference/addon-manifest.md +++ b/reference/addon-manifest.md @@ -1,3 +1,6 @@ +(ref-addon-manifest)= +# Addon manifest + The following table lists the valid keys in an addon manifest: | Name | Type | Description | Allowed values | @@ -7,8 +10,8 @@ The following table lists the valid keys in an addon manifest: | `provides.abi-support`| string array | Tells AMS that this addon adds support for the given architecture even if the application doesn't support it natively. Use this when your addon brings instruction translation or provides libraries for other architectures. | `arm64-v8a`, `armeabi-v7a`, `armeabi` | | `hooks.timeout`| string | Execution timeout for each hook that is included in an addon. By default, the timeout is set to 5 minutes. It can be extended to up to 15 minutes. Configure this option if a hook takes longer than 5 minutes to finish. | `10m` | -## Related information +## Related topics -* [Addons](https://discourse.ubuntu.com/t/38727) -* [Tutorial: Create an addon](https://discourse.ubuntu.com/t/creating-an-addon/25284) -* [How to use addons](https://discourse.ubuntu.com/t/managing-addons/17759) \ No newline at end of file +* {ref}`tut-create-addon` +* {ref}`howto-create-addons` +* {ref}`howto-addons` \ No newline at end of file diff --git a/reference/amc-command-reference/landing.md b/reference/amc-command-reference/landing.md deleted file mode 100644 index cda27181..00000000 --- a/reference/amc-command-reference/landing.md +++ /dev/null @@ -1,37 +0,0 @@ -The Anbox Management Client (AMC) is a command line utility offered by Anbox Cloud that interacts with the [Anbox Management Service (AMS)](https://discourse.ubuntu.com/t/24321). - -Use `amc --help` or `amc --help` to display usage information for the tool and its commands. The following commands are available for use with `amc`: - -| Command | Description| -|---------|------------| -|[`addon`](https://discourse.ubuntu.com/t/40775) | Manage addons | -|[`application`](https://discourse.ubuntu.com/t/40776) | Manage applications | -|[`benchmark`](https://discourse.ubuntu.com/t/40777) | Benchmark your Anbox Cloud deployment | -|[`completion`](https://discourse.ubuntu.com/t/40778) | Generate the auto completion script for the specified shell | -|[`config`](https://discourse.ubuntu.com/t/40779) | Manage AMS configuration | -|[`delete`](https://discourse.ubuntu.com/t/40780) | Delete an instance | -|[`exec`](https://discourse.ubuntu.com/t/40781) | Execute a command inside an instance | -|[`help`](https://discourse.ubuntu.com/t/40782) | Help for a command | -|[`image`](https://discourse.ubuntu.com/t/40783) | Manage images | -|[`info`](https://discourse.ubuntu.com/t/40784) | Provide information about connected AMS service | -|[`init`](https://discourse.ubuntu.com/t/40785) | Initialise an instance | -|[`launch`](https://discourse.ubuntu.com/t/40786) | Launch an instance | -|[`list`](https://discourse.ubuntu.com/t/40787) | List instances | -|[`logs`](https://discourse.ubuntu.com/t/40788) | View runtime logs of an instance | -|[`node`](https://discourse.ubuntu.com/t/40789) | Manage nodes | -|[`remote`](https://discourse.ubuntu.com/t/40790) | Interact with remote AMS daemons | -|[`shell`](https://discourse.ubuntu.com/t/40791) | Open a shell inside a running instance | -|[`show`](https://discourse.ubuntu.com/t/40793) | Display information about an instance | -|[`show-log`](https://discourse.ubuntu.com/t/40792) | Display a particular instance's log file | -|[`start`](https://discourse.ubuntu.com/t/40794) | Start an existing instance | -|[`stop`](https://discourse.ubuntu.com/t/40795) | Stop a running instance | -|[`wait`](https://discourse.ubuntu.com/t/40796) | Wait for an instance to reach a specific condition | - -## Options - -You can use the following options or flags with the `amc` utility: - -| Option | Description | -|--------|-------------| -|`-h`, `--help` | Display help for the `amc` utility | -|`-v`, `--version` | Display version of the AMS | diff --git a/reference/ams-configuration.md b/reference/ams-configuration.md index 1d1107e0..74a5cc9d 100644 --- a/reference/ams-configuration.md +++ b/reference/ams-configuration.md @@ -1,68 +1,69 @@ - - +(ref-ams-configuration)= +# AMS configuration The Anbox Management Service (AMS) provides various configuration items to customise its behaviour. The following table lists the available configuration items and their meaning. -| Name | Type | Deprecated | Default | Description | -|-----|------|------------|---------------|-----------------------| -| `agent.api.fingerprint` | string | No | - | Fingerprint of certificate in the AMS trust store which is trusted when communicating with the stream agent. | -| `agent.api.token` | string | No | - | Token to be used for API authentication with stream agent. | -| `agent.api.url` | string | No | - | URL for stream agent API endpoint. | -| `application.addons` | string | No | - | Comma-separated list of addons that every application managed by AMS will use. See [How to enable an addon globally](https://discourse.ubuntu.com/t/enable-an-addon-globally/25285). | -| `application.auto_publish` | bool | No | true | If set to `true`, AMS automatically published new application versions when the bootstrap process is finished. `false` disables this. See [Publish application versions](https://discourse.ubuntu.com/t/update-an-application/24201#publish-application-versions-1). | -| `application.auto_update` | bool | No | true | If set to `true`, AMS automatically updates applications whenever any dependencies (parent image, addons, global configuration) change. `false` disables this. See [Configure automatic application updates](https://discourse.ubuntu.com/t/update-an-application/24201#configure-automatic-application-updates-3). | -| `application.default_abi` | string | No | - | Default Android ABI that applications should use. See [Android ABIs](https://developer.android.com/ndk/guides/abis) for a list of available ABIs. | -| `application.max_published_versions` | integer | No | 3 | Maximum number of published versions per application. If the number of versions of an application exceeds this configuration, AMS will automatically clean up older versions. | -| `container.apt_mirror` | string | Yes | - | APT mirror to use within the containers. By default, `http://archive.ubuntu.com` (amd64) or `http://ports.ubuntu.com` (arm64) is used. This configuration item is deprecated since 1.20, use `instance.apt_mirror` instead. | -| `container.default_platform` | string | Yes | - | The name of the platform that Anbox Cloud uses by default to launch containers. This configuration item is deprecated since 1.20, use `instance.default_platform` instead. | -| `container.features` | string | Yes | - | Comma-separated list of features to enable (see list below). This configuration item is deprecated since 1.20, use `instance.features` instead. | -| `container.network_proxy` | string | Yes | - | Network proxy to use inside the containers. This configuration item is deprecated since 1.20, use `instance.network_proxy` instead. | -| `container.security_updates` | bool | Yes | true | If set to `true`, automatic Ubuntu security updates are applied during the application bootstrap process. `false` disables this. | -| `core.proxy_http` | string | No | - | HTTP proxy to use for HTTP requests that AMS performs. | -| `core.proxy_https` | string | No | - | HTTPS proxy to use for HTTPS requests that AMS performs. | -| `core.proxy_ignore_hosts` | string | No | - | Comma-separated list that defines the hosts for which a configured proxy is not used. | -| `core.trust_password` | string | No | - | The AMS trust password. | -| `cpu.limit_mode` | string | No | scheduler | The mode AMS uses to limit CPU access for an instance. See [About performance](https://discourse.ubuntu.com/t/about-performance/29416) for details. Possible values are: `scheduler`, `pinning` | -| `gpu.allocation_mode` | string | No | `all` | Method of allocating GPUs: `all` tells AMS to allocate all available GPUs on a system to an instance. `single` allocates only a single GPU. | -| `gpu.type` | string | No | `none` | Type of GPU: `none`, `intel`, `nvidia`, `amd` | -| `images.allow_insecure` | bool | No | false | If set to `true`, AMS allows accepting untrusted certificates provided by the configured image server. | -| `images.auth` | string | No | - | Authentication details for AMS to access the image server. When reading this configuration, a Boolean value that indicates whether the item is set is returned, to avoid exposing credentials. | -| `images.update_interval` | string | No | `5m` | Frequency of image updates (for example: 1h, 30m). | -| `images.url` | string | No | `https://images.anbox-cloud.io/stable/` | URL of the image server to use. | -| `images.version_lockstep` | bool | No | true | Whether to put the version of the latest pulled image and the AMS version in a lockstep. This ensures that a deployment is not automatically updated to newer image versions if AMS is still at an older version. This only applies for new major and minor but not patch version updates. | -| `instance.apt_mirror` | string | No | - | APT mirror to use within the instances. By default, `http://archive.ubuntu.com` (amd64) or `http://ports.ubuntu.com` (arm64) is used. | -| `instance.default_platform` | string | No | - | The name of the platform that Anbox Cloud uses by default to launch instances. | -| `instance.features` | string | No | - | Comma-separated list of features to enable (see list below). | -| `instance.network_proxy` | string | No | - | Network proxy to use inside the instances. | -| `instance.security_updates` | bool | No | true | If set to `true`, automatic Ubuntu security updates are applied during the application bootstrap process. `false` disables this. This configuration item is deprecated since 1.20, use `instance.security_updates` instead. | -| `load_balancer.url` | string | No | - | URL of the load balancer behind which AMS sits. The URL is handed to instances started by AMS to allow them to contact AMS through the load balancer and not via the address of an individual AMS instance. | -| `node.queue_size` | integer | No | 100 | Maximum size of the queue containing requests to start and stop instances per LXD node. Changing the value requires a restart of AMS. | -| `node.workers_per_queue` | integer | No | 4 | Number of workers processing instance start and stop requests. Changing the value requires a restart of AMS. | -| `registry.filter` | string | No | - | Comma-separated list of tags to filter for when applications are fetched from the [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761). If empty, no filter is applied. | -| `registry.fingerprint` | string | No | - | Fingerprint of the certificate that the [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) uses to TLS-secure its HTTPS endpoint. This is used by AMS for mutual TLS authentication with the registry. | -| `registry.mode` | string | No | `pull` | Mode in which the [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) client in AMS operates: `manual`, `pull`, `push` | -| `registry.update_interval` | string | No | `1h` | Frequency of [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) updates (for example: 1h, 30m). | -| `registry.url` | string | No | - | URL of the [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) to use. | -| `scheduler.strategy` | string | No | `spread` | Strategy that the internal instance scheduler in AMS uses to distribute instances across available LXD nodes: `binpack`, `spread` | - +| Name
*(Type, Default)* | Description | +|-----|-----------------------| +| `agent.api.fingerprint`
*(string, N/A)* | Fingerprint of certificate in the AMS trust store which is trusted when communicating with the stream agent. | +| `agent.api.token`
*(string, N/A)* | Token to be used for API authentication with stream agent. | +| `agent.api.url`
*(string, N/A)* | URL for stream agent API endpoint. | +| `application.addons`
*(string, N/A)* | Comma-separated list of addons that every application managed by AMS will use. See {ref}`howto-enable-addons-globally`. | +| `application.auto_publish`
*(bool, `true`)* | If set to `true`, AMS automatically published new application versions when the bootstrap process is finished. `false` disables this. See {ref}`sec-publish-app-versions`. | +| `application.auto_update`
*(bool, `true`)* | If set to `true`, AMS automatically updates applications whenever any dependencies (parent image, addons, global configuration) change. `false` disables this. See {ref}`sec-configure-automatic-app-updates`. | +| `application.default_abi`
*(string, N/A)* | Default Android ABI that applications should use. See [Android ABIs](https://developer.android.com/ndk/guides/abis) for a list of available ABIs. | +| `application.max_published_versions`
*(integer, `3`)* | Maximum number of published versions per application. If the number of versions of an application exceeds this configuration, AMS will automatically clean up older versions. | +| `container.apt_mirror`
*(string,
`http://archive.ubuntu.com` (AMD64)
`http://ports.ubuntu.com` (ARM64))*
*(Deprecated)* | APT mirror to use within the containers. This configuration item is deprecated since 1.20, use `instance.apt_mirror` instead. | +| `container.default_platform`
*(string, N/A)*
*(Deprecated)* | The name of the platform that Anbox Cloud uses by default to launch containers. This configuration item is deprecated since 1.20, use `instance.default_platform` instead. | +| `container.features`
*(string, N/A)*
*(Deprecated)* | Comma-separated list of features to enable (see list below). This configuration item is deprecated since 1.20, use `instance.features` instead. | +| `container.network_proxy`
*(string, N/A)*
*(Deprecated)* | Network proxy to use inside the containers. This configuration item is deprecated since 1.20, use `instance.network_proxy` instead. | +| `container.security_updates`
*(bool, `true`)*
*(Deprecated)* | If set to `true`, automatic Ubuntu security updates are applied during the application bootstrap process. `false` disables this. | +| `core.proxy_http`
*(string, N/A)* | HTTP proxy to use for HTTP requests that AMS performs. | +| `core.proxy_https`
*(string, N/A)* | HTTPS proxy to use for HTTPS requests that AMS performs. | +| `core.proxy_ignore_hosts`
*(string, N/A)* | Comma-separated list that defines the hosts for which a configured proxy is not used. | +| `core.trust_password`
*(string, N/A)* | The AMS trust password. | +| `cpu.limit_mode`
*(string, `scheduler`)* | The mode AMS uses to limit CPU access for an instance. See {ref}`exp-performance` for details. Possible values are: `scheduler`, `pinning` | +| `gpu.allocation_mode`
*(string, `all`)* | Method of allocating GPUs: `all` tells AMS to allocate all available GPUs on a system to an instance. `single` allocates only a single GPU. | +| `gpu.type`
*(string, `none`)* | Type of GPU: `none`, `intel`, `nvidia`, `amd` | +| `images.allow_insecure`
*(bool, `false`)* | If set to `true`, AMS allows accepting untrusted certificates provided by the configured image server. | +| `images.auth`
*(string, N/A)* | Authentication details for AMS to access the image server. When reading this configuration, a Boolean value that indicates whether the item is set is returned, to avoid exposing credentials. | +| `images.update_interval`
*(string, `5m`)* | Frequency of image updates (for example: 1h, 30m). | +| `images.url`
*(string, `https://images.anbox-cloud.io/stable/`)* | URL of the image server to use. | +| `images.version_lockstep`
*(bool, `true`)* | Whether to put the version of the latest pulled image and the AMS version in a lockstep. This ensures that a deployment is not automatically updated to newer image versions if AMS is still at an older version. This only applies for new major and minor but not patch version updates. | +| `instance.apt_mirror`
*(string,
`http://archive.ubuntu.com` (AMD64) `http://ports.ubuntu.com` (ARM64))* | APT mirror to use within the instances. | +| `instance.default_platform`
*(string, N/A)* | The name of the platform that Anbox Cloud uses by default to launch instances. | +| `instance.features`
*(string, N/A)* | Comma-separated list of features to enable (see list below). | +| `instance.network_proxy`
*(string, N/A)* | Network proxy to use inside the instances. | +| `instance.security_updates`
*(bool, `true`)* | If set to `true`, automatic Ubuntu security updates are applied during the application bootstrap process. `false` disables this. This configuration item is deprecated since 1.20, use `instance.security_updates` instead. | +| `load_balancer.url`
*(string, N/A)* | URL of the load balancer behind which AMS sits. The URL is handed to instances started by AMS to allow them to contact AMS through the load balancer and not via the address of an individual AMS instance. | +| `node.queue_size`
*(integer, `100`)* | Maximum size of the queue containing requests to start and stop instances per LXD node. Changing the value requires a restart of AMS. | +| `node.workers_per_queue`
*(integer, `4`)* | Number of workers processing instance start and stop requests. Changing the value requires a restart of AMS. | +| `registry.filter`
*(string, N/A)* | Comma-separated list of tags to filter for when applications are fetched from the {ref}`exp-aar`. If empty, no filter is applied. | +| `registry.fingerprint`
*(string, N/A)* | Fingerprint of the certificate that the {ref}`exp-aar` uses to TLS-secure its HTTPS endpoint. This is used by AMS for mutual TLS authentication with the registry. | +| `registry.mode`
*(string, `pull`)* | Mode in which the {ref}`exp-aar` client in AMS operates: `manual`, `pull`, `push` | +| `registry.update_interval`
*(string, `1h`)* | Frequency of {ref}`exp-aar` updates (for example: 1h, 30m). | +| `registry.url`
*(string, N/A)* | URL of the {ref}`exp-aar` to use. | +| `scheduler.strategy`
*(string, `spread`)* | Strategy that the internal instance scheduler in AMS uses to distribute instances across available LXD nodes: `binpack`, `spread` | + +(sec-node-configuration)= ## Node-specific configuration In a cluster setup, there are configuration items that can be customised for each node. The following table lists the available configuration items and their meaning. -| Name | Type | Deprecated | Default | Description | -|-----|------|------------|---------------|-----------------------| -| `cpu-allocation-rate` | integer | No | 4 | CPU allocation rate used for [over-committing resources](https://discourse.ubuntu.com/t/about-capacity-planning/28717#over-committing-resources-3). | -| `cpus` | integer | No | all available | Number of CPUs dedicated to instances. | -| `gpu-encoder-slots` | integer | No | 0 (for nodes without GPU or with AMD GPU)
32 (for nodes with NVIDIA GPU)
10 (for nodes with Intel GPU) | Number of GPU encoder slots available on the node. | -| `gpu-slots` | integer | No | 0 (for nodes without GPU)
32 (for nodes with NVIDIA GPU)
10 (for nodes with AMD or Intel GPU) | Number of [GPU slots](https://discourse.ubuntu.com/t/about-capacity-planning/28717#gpu-slots-2) available on the node. | -| `memory` | integer | No | all available | Memory dedicated to instances. | -| `memory-allocation-rate` | integer | No | 2 | Memory allocation rate used for [over-committing resources](https://discourse.ubuntu.com/t/about-capacity-planning/28717#over-committing-resources-3). | -| `public-address` | string | No | - | The public, reachable address of the node. | -| `subnet` | string | No | - | The network subnet of the machine where the node runs. | -| `tags` | string | No | - | Tags to identify the node. | -| `unschedulable` | bool | No | false | If set to `true`, the node cannot be scheduled, which prevents new instances from being launched on it. | - -See [Configure cluster nodes](https://discourse.ubuntu.com/t/configure-cluster-nodes/28716) for instructions on how to set these configuration items. +| Name
*(Type, Default)* | Description | +|--------------------------|-------------------------| +| `cpu-allocation-rate`
*(integer, `4`)* | CPU allocation rate used for over-committing resources. See {ref}`sec-over-committing`. | +| `cpus`
*(integer, all available)* | Number of CPUs dedicated to instances. | +| `gpu-encoder-slots`
*(integer,
`0` for nodes without GPU or with AMD GPU
`32` for nodes with NVIDIA GPU
`10` for nodes with Intel GPU)* | Number of GPU encoder slots available on the node. | +| `gpu-slots`
*(integer,
`0` for nodes without GPU
`32` for nodes with NVIDIA GPU
`10` for nodes with AMD or Intel GPU)* | Number of GPU slots available on the node. See {ref}`sec-gpu-slots`. | +| `memory`
*(integer, all available)* | Memory dedicated to instances. | +| `memory-allocation-rate`
*(integer, `2`)* | Memory allocation rate used for over-committing resources. See {ref}`sec-over-committing`. | +| `public-address`
*(string, N/A)*| The public, reachable address of the node. | +| `subnet`
*(string, N/A)* | The network subnet of the machine where the node runs. | +| `tags`
*(string, N/A)*| Tags to identify the node. | +| `unschedulable`
*(bool, `false`)* | When set to `true`, the node cannot be scheduled, which prevents new instances from being launched on it. | + +See {ref}`howto-configure-cluster-nodes` for instructions on how to set these configuration items. ## Objects managed by AMS @@ -85,6 +86,3 @@ When you create an instance, the same criteria apply to the following options as The object ids are generated by AMS and have a length of 20 characters. - - - diff --git a/reference/ams-configuration.tmpl.md b/reference/ams-configuration.tmpl.md deleted file mode 100644 index 1b63a094..00000000 --- a/reference/ams-configuration.tmpl.md +++ /dev/null @@ -1,36 +0,0 @@ -The Anbox Management Service (AMS) provides various configuration items to customise its behaviour. The following table lists the available configuration items and their meaning. - - - -## Node-specific configuration - -In a cluster setup, there are configuration items that can be customised for each node. The following table lists the available configuration items and their meaning. - - - -See [Configure cluster nodes](https://discourse.ubuntu.com/t/configure-cluster-nodes/28716) for instructions on how to set these configuration items. - -## Objects managed by AMS - -AMS manages various objects such as applications, images, instances, nodes and addons. - -The object names must adhere to the following criteria: - -* Minimum character limit: 3 -* Maximum character limit: 255 -* Can contain: - - Alphabets (a-z, A-Z) - - Numbers (0-9) - - Allowed special characters: `-` (hyphen), `_` (underscore), `:` (colon), `.` (period). - -When you create an instance, the same criteria apply to the following options as well: - -* `boot_activity` -* `platform` -* `boot_package` - -The object ids are generated by AMS and have a length of 20 characters. - - - - diff --git a/reference/ams-configuration.yaml b/reference/ams-configuration.yaml deleted file mode 100644 index 6622409a..00000000 --- a/reference/ams-configuration.yaml +++ /dev/null @@ -1,368 +0,0 @@ ---- -all: - application.addons: - type: "string" - default: "-" - description: >- - Comma-separated list of addons that every application managed by - AMS will use. See - [How to enable an addon globally](https://discourse.ubuntu.com/t/enable-an-addon-globally/25285). - deprecated: "No" # Unquoted No will be considered as false in YAML parsing - application.auto_publish: - type: "bool" - default: "true" - description: >- - If set to `true`, AMS automatically published new application - versions when the bootstrap process is finished. `false` - disables this. See - [Publish application versions](https://discourse.ubuntu.com/t/update-an-application/24201#publish-application-versions-1). - deprecated: "No" - application.auto_update: - type: "bool" - default: "true" - description: >- - If set to `true`, AMS automatically updates applications - whenever any dependencies (parent image, addons, global - configuration) change. `false` disables this. See - [Configure automatic application updates](https://discourse.ubuntu.com/t/update-an-application/24201#configure-automatic-application-updates-3). - deprecated: "No" - application.default_abi: - type: "string" - default: "-" - description: >- - Default Android ABI that applications should use. See - [Android ABIs](https://developer.android.com/ndk/guides/abis) - for a list of available ABIs. - deprecated: "No" - application.max_published_versions: - type: "integer" - default: "3" - description: >- - Maximum number of published versions per application. If the - number of versions of an application exceeds this configuration, - AMS will automatically clean up older versions. - deprecated: "No" - container.apt_mirror: - type: "string" - default: "-" - description: >- - APT mirror to use within the containers. By default, - `http://archive.ubuntu.com` (amd64) or `http://ports.ubuntu.com` - (arm64) is used. This configuration item is deprecated since 1.20, - use `instance.apt_mirror` instead. - deprecated: "Yes" - instance.apt_mirror: - type: "string" - default: "-" - description: >- - APT mirror to use within the instances. By default, - `http://archive.ubuntu.com` (amd64) or `http://ports.ubuntu.com` - (arm64) is used. - deprecated: "No" - container.default_platform: - type: "string" - default: "-" - description: >- - The name of the platform that Anbox Cloud uses by default to launch - containers. This configuration item is deprecated since 1.20, - use `instance.default_platform` instead. - deprecated: "Yes" - instance.default_platform: - type: "string" - default: "-" - description: >- - The name of the platform that Anbox Cloud uses by default to launch - instances. - deprecated: "No" - container.features: - type: "string" - default: "-" - description: >- - Comma-separated list of features to enable (see list below). - This configuration item is deprecated since 1.20, use - `instance.features` instead. - deprecated: "Yes" - instance.features: - type: "string" - default: "-" - description: >- - Comma-separated list of features to enable (see list below). - deprecated: "No" - container.network_proxy: - type: "string" - default: "-" - description: >- - Network proxy to use inside the containers. This configuration - item is deprecated since 1.20, use `instance.network_proxy` - instead. - deprecated: "Yes" - instance.network_proxy: - type: "string" - default: "-" - description: >- - Network proxy to use inside the instances. - deprecated: "No" - container.security_updates: - type: "bool" - default: "true" - description: >- - If set to `true`, automatic Ubuntu security updates are applied - during the application bootstrap process. `false` disables this. - deprecated: "Yes" - instance.security_updates: - type: "bool" - default: "true" - description: >- - If set to `true`, automatic Ubuntu security updates are applied - during the application bootstrap process. `false` disables this. - This configuration item is deprecated since 1.20, use - `instance.security_updates` instead. - deprecated: "No" - core.proxy_http: - type: "string" - default: "-" - description: >- - HTTP proxy to use for HTTP requests that AMS performs. - deprecated: "No" - core.proxy_https: - type: "string" - default: "-" - description: >- - HTTPS proxy to use for HTTPS requests that AMS performs. - deprecated: "No" - core.proxy_ignore_hosts: - type: "string" - default: "-" - description: >- - Comma-separated list that defines the hosts for which a - configured proxy is not used. - deprecated: "No" - core.trust_password: - type: "string" - default: "-" - description: >- - The AMS trust password. - deprecated: "No" - cpu.limit_mode: - type: "string" - default: "scheduler" - description: >- - The mode AMS uses to limit CPU access for an instance. See - [About performance](https://discourse.ubuntu.com/t/about-performance/29416) for details. - Possible values are: `scheduler`, `pinning` - deprecated: "No" - gpu.allocation_mode: - type: "string" - default: "`all`" - description: >- - Method of allocating GPUs: `all` tells AMS to allocate all - available GPUs on a system to an instance. `single` allocates - only a single GPU. - deprecated: "No" - gpu.type: - type: "string" - default: "`none`" - description: >- - Type of GPU: `none`, `intel`, `nvidia`, `amd` - deprecated: "No" - images.allow_insecure: - type: "bool" - default: "false" - description: >- - If set to `true`, AMS allows accepting untrusted certificates - provided by the configured image server. - deprecated: "No" - images.auth: - type: "string" - default: "-" - description: >- - Authentication details for AMS to access the image server. When - reading this configuration, a Boolean value that indicates - whether the item is set is returned, to avoid exposing - credentials. - deprecated: "No" - images.update_interval: - type: "string" - default: "`5m`" - description: >- - Frequency of image updates (for example: 1h, 30m). - deprecated: "No" - images.url: - type: "string" - default: "`https://images.anbox-cloud.io/stable/`" - description: >- - URL of the image server to use. - deprecated: "No" - images.version_lockstep: - type: "bool" - default: "true" - description: >- - Whether to put the version of the latest pulled image and the - AMS version in a lockstep. This ensures that a deployment is not - automatically updated to newer image versions if AMS is still at - an older version. This only applies for new major and minor but - not patch version updates. - deprecated: "No" - load_balancer.url: - type: "string" - default: "-" - description: >- - URL of the load balancer behind which AMS sits. The URL is - handed to instances started by AMS to allow them to contact AMS - through the load balancer and not via the address of an - individual AMS instance. - deprecated: "No" - node.queue_size: - type: "integer" - default: "100" - description: >- - Maximum size of the queue containing requests to start and stop - instances per LXD node. Changing the value requires a restart of - AMS. - deprecated: "No" - node.workers_per_queue: - type: "integer" - default: "4" - description: >- - Number of workers processing instance start and stop requests. - Changing the value requires a restart of AMS. - deprecated: "No" - registry.filter: - type: "string" - default: "-" - description: >- - Comma-separated list of tags to filter for when applications are - fetched from the - [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761). - If empty, no filter is applied. - deprecated: "No" - registry.fingerprint: - type: "string" - default: "-" - description: >- - Fingerprint of the certificate that the - [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) - uses to TLS-secure its HTTPS endpoint. This is used by AMS for - mutual TLS authentication with the registry. - deprecated: "No" - registry.mode: - type: "string" - default: "`pull`" - description: >- - Mode in which the - [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) - client in AMS operates: `manual`, `pull`, `push` - deprecated: "No" - registry.update_interval: - type: "string" - default: "`1h`" - description: >- - Frequency of - [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) - updates (for example: 1h, 30m). - deprecated: "No" - registry.url: - type: "string" - default: "-" - description: >- - URL of the - [Anbox Application Registry](https://discourse.ubuntu.com/t/application-registry/17761) - to use. - deprecated: "No" - scheduler.strategy: - type: "string" - default: "`spread`" - description: >- - Strategy that the internal instance scheduler in AMS uses to - distribute instances across available LXD nodes: `binpack`, - `spread` - deprecated: "No" - agent.api.fingerprint: - type: "string" - default: "-" - description: >- - Fingerprint of certificate in the AMS trust store which is - trusted when communicating with the stream agent. - deprecated: "No" - agent.api.token: - type: "string" - default: "-" - description: >- - Token to be used for API authentication with stream agent. - deprecated: "No" - agent.api.url: - type: "string" - default: "-" - description: >- - URL for stream agent API endpoint. - deprecated: "No" -node: - cpu-allocation-rate: - type: "integer" - default: "4" - description: >- - CPU allocation rate used for - [over-committing resources](https://discourse.ubuntu.com/t/about-capacity-planning/28717#over-committing-resources-3). - deprecated: "No" - cpus: - type: "integer" - default: "all available" - description: >- - Number of CPUs dedicated to instances. - deprecated: "No" - gpu-encoder-slots: - type: "integer" - default: >- - 0 (for nodes without GPU or with AMD GPU)
32 (for nodes with - NVIDIA GPU)
10 (for nodes with Intel GPU) - description: >- - Number of GPU encoder slots available on the node. - deprecated: "No" - gpu-slots: - type: "integer" - default: >- - 0 (for nodes without GPU)
32 (for nodes with NVIDIA - GPU)
10 (for nodes with AMD or Intel GPU) - description: >- - Number of - [GPU slots](https://discourse.ubuntu.com/t/about-capacity-planning/28717#gpu-slots-2) - available on the node. - deprecated: "No" - memory: - type: "integer" - default: "all available" - description: >- - Memory dedicated to instances. - deprecated: "No" - memory-allocation-rate: - type: "integer" - default: "2" - description: >- - Memory allocation rate used for - [over-committing resources](https://discourse.ubuntu.com/t/about-capacity-planning/28717#over-committing-resources-3). - deprecated: "No" - public-address: - type: "string" - default: "-" - description: >- - The public, reachable address of the node. - deprecated: "No" - subnet: - type: "string" - default: "-" - description: >- - The network subnet of the machine where the node runs. - deprecated: "No" - tags: - type: "string" - default: "-" - description: >- - Tags to identify the node. - deprecated: "No" - unschedulable: - type: "bool" - default: "false" - description: >- - If set to `true`, the node cannot be scheduled, which prevents - new instances from being launched on it. - deprecated: "No" diff --git a/reference/ams-http-api.md b/reference/ams-http-api.md deleted file mode 100644 index 1c39ece8..00000000 --- a/reference/ams-http-api.md +++ /dev/null @@ -1,2398 +0,0 @@ -All the communications between AMS and its clients happen using a RESTful API over HTTP which is then encapsulated over either TLS for remote operations or a Unix socket for local operations - -Not all REST API endpoints require authentication: - -* GET to `/` is allowed for everyone -* GET to `/1.0` is allowed for everyone -* GET to `/1.0/version` is allowed for everyone - -Some endpoints require an additional authentication token to ensure that the requester is authorised to access the resource: - -* GET to `/1.0/artifacts` -* PATCH to `/1.0/containers/` - - -## API versioning - -The details of a version of the API can be retrieved using `GET /`. -For example `GET /1.0` - -The reason for a major API bump is if the API breaks backward compatibility. - -Feature additions done without breaking backward compatibility only result in addition to `api_extensions` which can be used by the client to check if a given feature is supported by the server. - -## Return values - -There are three standard return types: - - * Standard return value - * Background operation - * Error - -### Standard return value - -For a standard synchronous operation, the following dict is returned: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "metadata": {} # Extra resource/action specific metadata -} -``` - -HTTP code must be 200. - -### Background operation - -When a request results in a background operation, the HTTP code is set to 202 (Accepted) -and the Location HTTP header is set to the operation URL. - -The body is a dict with the following structure: - -```json -{ - "type": "async", - "status": "OK", - "status_code": 100, - "operation": "/1.0/containers/", # URL to the background operation - "metadata": {} # Operation metadata (see below) -} -``` - -The operation metadata structure looks like: - -```json -{ - "id": "c6832c58-0867-467e-b245-2962d6527876", # UUID of the operation - "class": "task", # Class of the operation (task, web socket or token) - "created_at": "2018-04-02T16:49:36.341463206+02:00", # When the operation was created - "updated_at": "2018-04-02T16:49:36.341463206+02:00", # Last time the operation was updated - "status": "Running", # String version of the operation's status - "status_code": 103, # Integer version of the operation's status (use this rather than status) - "resources": { # Dictionary of resource types (container, snapshots, images) and affected resources - "containers": [ - "/1.0/containers/3apqo5te" - ] - }, - "metadata": null, # Metadata specific to the operation in question (in this case, nothing) - "may_cancel": false, # Whether the operation can be canceled (DELETE over REST) - "err": "" # The error string should the operation have failed -} -``` - -The body is mostly provided as a user friendly way of seeing what's going on without having to pull the target operation, all information in the body can also be retrieved from the background operation URL. - -### Error - -There are various situations in which something may immediately go wrong, in those cases, the following return value is used: - -```json -{ - "type": "error", - "error": "Failure", - "error_code": 400, - "metadata": {} # More details about the error -} -``` - -HTTP code must be one of 400, 401, 403, 404, 409, 412 or 500. - -## Status codes - -The AMS REST API often has to return status information, be that the reason for an error, the current state of an operation or the state of the various resources it exports. - -To make it simple to debug, all of those are always doubled. There is a numeric representation of the state which is guaranteed never to change and can be relied on by API clients. Then there is a text version meant to make it easier for people manually using the API to figure out what's happening. - -In most cases, those will be called status and `status_code`, the former being the user friendly string representation and the latter the fixed numeric value. - -The codes are always 3 digits, with the following ranges: - - * 100 to 199: resource state (started, stopped, ready, ...) - * 200 to 399: positive action result - * 400 to 599: negative action result - * 600 to 999: future use - -### List of current status codes - -Code | Meaning ----|------ -100 | Operation created -101 | Started -102 | Stopped -103 | Running -104 | Cancelling -105 | Pending -106 | Starting -107 | Stopping -108 | Aborting -109 | Freezing -110 | Frozen -111 | Thawed -200 | Success -400 | Failure -401 | Cancelled - -## Recursion - -To optimise queries of large lists, recursion is implemented for collections. A `recursion` argument can be passed to a GET query against a collection. - -The default value is 0 which means that collection member URLs are returned. Setting it to 1 will have those URLs be replaced by the object they point to (typically a dict). - -Recursion is implemented by simply replacing any pointer to a job (URL) by the object itself. - -## Async operations - -Any operation which may take more than a second to be done must be done in the background, returning a background operation ID to the client. - -The client will then be able to either poll for a status update or wait for a notification using the long-poll API. - -## Notifications - -A web-socket based API is available for notifications, different notification types exist to limit the traffic going to the client. - -It's recommended that the client always subscribes to the operations notification type before triggering remote operations so that it doesn't have to then poll for their status. - -## PUT vs PATCH - -The AMS API supports both PUT and PATCH to modify existing objects. - -PUT replaces the entire object with a new definition, it's typically called after the current object state was retrieved through GET. - -To avoid race conditions, the ETag header should be read from the GET response and sent as If-Match for the PUT request. This will cause AMS to fail the request if the object was modified between GET and PUT. - -PATCH can be used to modify a single field inside an object by only specifying the property that you want to change. To unset a key, setting it to empty will usually do the trick, but there are cases where PATCH won't work and PUT needs to be used instead. - -## Authorisation - -Some operation may require a token to be included in the HTTP Authorisation header like this: - - * `Authorization: bearer ` - -No matter if the request is already authenticated using a trusted certificate. If the token is not valid, the request is rejected by the server. This ensures that only authorised clients can access those endpoints. - -## File upload - -Some operations require uploading a payload. To prevent the difficulties of handling multipart requests, another solution has been taken: A unique file is uploaded and its bytes are included in the body of the request. Some metadata associated with the file is included in extra HTTP headers: - - * X-AMS-Fingerprint: fingerprint of the payload being added - * X-AMS-Request: metadata for the payload. This is a JSON, specific for the operation. - -## API structure - - * [`/`](heading--#) - * [`/1.0`](#heading--10) - * [`/1.0/addons`](#heading--10addons) - * [`/1.0/addons/`](#heading--10addonsname) - * [`/1.0/addons//`](#heading--10addonsnameversion) - * [`/1.0/applications`](#heading--10applications) - * [`/1.0/applications/`](#heading--10applicationsname) - * [`/1.0/applications//manifest`](#heading--10applicationsnamemanifest) - * [`/1.0/applications//`](#heading--10applicationsnameversion) - * [`/1.0/applications///manifest`](#heading--10applicationsnameversionmanifest) - * [`/1.0/certificates`](#heading--10certificates) - * [`/1.0/certificates/`](#heading--10certificatesid) - * [`/1.0/config`](#heading--10config) - * [`/1.0/containers`](#heading--10containers) - * [`/1.0/containers/`](#heading--10containersid) - * [`/1.0/containers//logs`](#heading--10containersidlogs) - * [`/1.0/containers//logs/`](#heading--10containersidlogsname) - * [`/1.0/events`](#heading--10events) - * [`/1.0/images`](#heading--10images) - * [`/1.0/images/`](#heading--10images) - * [`/1.0/images//`](#heading--10imagesidversion) - * [`/1.0/nodes`](#heading--10nodes) - * [`/1.0/nodes/`](#heading--10nodesname) - * [`/1.0/operations`](#heading--10operations) - * [`/1.0/operations/`](#heading--10operationsuuid) - * [`/1.0/operations//wait`](#heading--10operationsuuidwait) - * [`/1.0/operations//websocket`](#heading--10operationsuuidwebsocket) - * [`/1.0/tasks`](#heading--10tasks) - * [`/1.0/version`](#heading--10version) - -## API details - -### `/1.0/` -#### GET - * Description: Server configuration - * Authentication: guest, untrusted or trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0 -``` - -Output (if trusted): - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "api_extensions": [], // List of API extensions added after the API was marked stable - "api_status": "stable", // API implementation status (one of, development, stable or deprecated) - "api_version": "1.0", // The API version as a string - "auth": "trusted", // Authentication state, one of "guest", "untrusted" or "trusted" - "auth_methods": [ // Authentication method - "2waySSL" - ] - } -} -``` - - -### `/1.0/addons` -#### GET - * Description: List of addons - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/addons -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - "/1.0/addons/foo", - "/1.0/addons/bar" - ] -} -``` - -#### POST - * Description: Create a new addon - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP payload upload case, the following headers may be set by the client: - -* `Content-Type:`: application/octet-stream (mandatory field) -* `X-AMS-Request`: JSON format metadata (mandatory field) -* `X-AMS-Fingerprint:`: SHA-256 (if set, the uploaded payload must match) - -For an addon upload, the `X-AMS-Request` header is comprised of: - -```json -{ - "name": "my-addon" -} -``` - -The payload to upload must be a tarball compressed with bzip2 or a zip archive. Also, it must contain a `manifest.yaml` which declares the basic addon information and at least an install hook for the creation. For the layout of the addon and supported syntax, please refer to [How to use addons](https://discourse.ubuntu.com/t/managing-addons/17759) for more details. - -Example: -```bash -curl -s --header "Content-Type: application/octet-stream" --header 'X-AMS-Request: {"name": "my-addon"}' -X POST --insecure --cert client.crt --key client.key --data-binary @addon.tar.bz2 /1.0/addons -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/603055f6-5cc6-4668-9f2d-28d8bce64024", - "error_code": 0, - "error": "", - "metadata": { - "id": "603055f6-5cc6-4668-9f2d-28d8bce64024", - "class": "task", - "description": "Creating addon", - "created_at": "2018-07-21T03:02:22.091350247Z", - "updated_at": "2018-07-21T03:02:22.091350247Z", - "status": "Running", - "status_code": 103, - "resources": { - "addons": [ - "/1.0/addons/my-addon" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of an addon upload operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/addons/` -#### GET - * Description: Retrieve information about an addon - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/addons/my-addon -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "name": "my-addon", - "versions": [ // List of versions - { - "version": 0, // Version number - "fingerprint": "60d8af000f50527f83f30673586329717384d7243858fd6216a8eeb488802d4a", // SHA-256 fingerprint - "size": 283, // Size in bytes - "created_at": 1611716542 // Seconds since Jan 01 1970. (UTC) - } - ], - "used_by": null // List of applications to use this addon - } -} -``` - -#### DELETE - * Description: Delete an addon - * Authentication: trusted - * Operation: async - * Cancellable: no - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key /1.0/addons/my-addon -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/0cb31170-c2af-429b-97bc-016c94daf6a2", - "error_code": 0, - "error": "", - "metadata": { - "id": "0cb31170-c2af-429b-97bc-016c94daf6a2", - "class": "task", - "description": "Deleting addon", - "created_at": "2018-07-27T03:26:46.696046272Z", - "updated_at": "2018-07-27T03:26:46.696046272Z", - "status": "Running", - "status_code": 103, - "resources": { - "addons": [ - "/1.0/addons/my-addon" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an addon deletion operation, please refer to [`/1.0/operations`](#heading--10operations) - -#### PATCH (ETag supported) - * Description: Update addon metadata and creates a new addon version for it - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP addon update case, the following headers may be set by the client: - -* `Content-Type:`: application/octet-stream (mandatory field) -* `X-AMS-Request`: JSON format metadata (mandatory field) -* `X-AMS-Fingerprint:`: SHA-256 (if set, the uploaded payload must match) - -For an addon patch, the `X-AMS-Request` header is comprised of an empty JSON object - -```json -{} -``` - -Example -```bash -curl -s --header "Content-Type: application/octet-stream" --header 'X-AMS-Request: {}' -X PATCH --insecure --cert client.crt --key client.key --data-binary @addon.tar.bz2 /1.0/addons/my-addon -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/7022c28e-ed5b-484a-9bb2-43706b01e229", - "error_code": 0, - "error": "", - "metadata": { - "id": "7022c28e-ed5b-484a-9bb2-43706b01e229", - "class": "task", - "description": "Updating addon", - "created_at": "2018-07-27T03:46:31.431217757Z", - "updated_at": "2018-07-27T03:46:31.431217757Z", - "status": "Running", - "status_code": 103, - "resources": { - "addons": [ - "/1.0/addons/my-addon" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of an addon update operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/addons//` -#### DELETE - * Description: Delete specific version of an addon - * Authentication: trusted - * Operation: async - * Cancellable: no - -Example -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key /1.0/addons/my-addon/1 -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/bc20dcd5-6e8c-4feb-b3f0-cb8d2fd7238a", - "error_code": 0, - "error": "", - "metadata": { - "id": "bc20dcd5-6e8c-4feb-b3f0-cb8d2fd7238a", - "class": "task", - "description": "Deleting addon version", - "created_at": "2018-07-27T03:55:58.005511611Z", - "updated_at": "2018-07-27T03:55:58.005511611Z", - "status": "Running", - "status_code": 103, - "resources": { - "addons": [ - "/1.0/addons/my-addon" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of an addon version deletion operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/applications` -#### GET - * Description: List of applications - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/applications -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - "/1.0/applications/c08fr0gj1qm443dtn870" - ] -} -``` - -#### POST - * Description: Create a new application - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP application upload case, the following headers may be set by the client: - -* `Content-Type:`: application/octet-stream (mandatory field) -* `X-AMS-Fingerprint:`: SHA-256 (if set, the uploaded payload must match) - -The payload to upload must be a tarball compressed with bzip2 or a zip archive. Also it must contain a `manifest.yaml` which declares the basic application information for the creation. For the layout of the application and supported syntax, see [How to create an application](https://discourse.ubuntu.com/t/create-an-application/24198) for more details. - -To support the following syntax in the application `manifest.yaml`, the server requires a corresponding extension - -Syntax in manifest | Extension -----------------|------------------------------------ -watchdog | `application_watchdog_settings` -resources | `application_resource_customization` -services | `application_services_configuration` -version | `application_manifest_version` -video-encoder | `application_gpu_encoder` - -Example -```bash -curl -s -X POST --header "Content-Type: application/octet-stream" --insecure --cert client.crt --key client.key --data-binary @app.tar.bz2 /1.0/applications -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/d1cb8d8f-1471-40d7-9b1a-3c222afbde53", - "error_code": 0, - "error": "", - "metadata": { - "id": "d1cb8d8f-1471-40d7-9b1a-3c222afbde53", - "class": "task", - "description": "Creating application", - "created_at": "2018-07-27T05:43:30.66261346Z", - "updated_at": "2018-07-27T05:43:30.66261346Z", - "status": "Running", - "status_code": 103, - "resources": { - "applications": [ - "/1.0/applications/c08fr0gj1qm443dtn870" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of an application creation operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/applications/` -#### GET - * Description: Retrieve information about an application - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/applications/my-app -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "id": "c08fr0gj1qm443dtn870", - "name": "my-app", - "status_code": 2, - "status": "ready", // Application status - "instance_type": "a4.3", // Instance type - "boot_package": "com.lolo.io.onelist", // Boot application - "parent_image_id": "btavtegj1qm58qg7ru50", - "published": true, - "versions": [ // List of all versions - { - "number": 0, - "manifest_version": "", - "parent_image_id": "btavtegj1qm58qg7ru50", // Base image the application is created from - "parent_image_version": 0, // Base image version - "status_code": 3, - "status": "active", // Application status - "published": true, // Publication status - "created_at": 1532150640, - "boot_activity": "", // Boot activity on application start - "required_permissions": null, // Required Android application permissions - "addons": [], // Attached addons - "extra_data": {}, // Extra data to be installed on application creation - "error_message": "", - "video_encoder": "gpu-preferred", // Video encoder settings - "watchdog": { // Watchdog settings - "disabled": false, - "allowed-packages": null - } - } - ], - "addons": [], - "created_at": 1532150640, - "immutable": false, - "tags": null, - "resources": { // Application resources - "gpu-slots": -1 - }, - "abi": "x86_64", // Application ABI - "inhibit_auto_updates": false // Application automatically update configuration - } -} -``` - -#### PATCH (ETag supported) - * Description: Update existing application - * Authentication: trusted - * Operation: sync - * Cancellable: no - -An application can be updated with either a new package or specific fields. -The `Content-Type` header of HTTP patch request is different when uploading -an application in either way. - -Update methods | Content-Type -----------------|------------------------------------ -With a new package | `application/octet-stream` -With specified fields | `application/json` - -An application package can be uploaded with a bzip2 compressed payload if the former method is taken. - -Example -```bash -curl -s --header "Content-Type: application/octet-stream" -X PATCH --insecure --cert client.crt --key client.key --data-binary @app_1.tar.bz2 /1.0/applications/my-app -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/e1dc826e-8627-4225-94b1-808ac0e40bfb", - "error_code": 0, - "error": "", - "metadata": { - "id": "e1dc826e-8627-4225-94b1-808ac0e40bfb", - "class": "task", - "description": "Updating application", - "created_at": "2018-07-27T06:18:33.157030462Z", - "updated_at": "2018-07-27T06:18:33.157030462Z", - "status": "Running", - "status_code": 103, - "resources": { - "applications": [ - "/1.0/applications/my-app" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -For the specific field update case, a JSON format payload is accepted. - -```json -{ - "tags": [ "game" ], - "instance-type": "a4.3" -} -``` - -Example -```bash -curl -s --header "Content-Type: application/json" -X PATCH --insecure --cert client.crt --key client.key --data "$payload" /1.0/applications/my-app -``` - -To monitor the status of an application update operation, please refer to [`/1.0/operations`](#heading--10operations) - -The following fields can be modified when updating an application. Changing some of those fields will lead to creating another application version. - -Supported update field | Will create a new application version -----------------|------------------------------------ -image | no -instance-type | no -tags | no -addons | no -resources | no -inhibit_auto_updates | no -services | yes -watchdog |yes -boot_activity | yes -required_permissions | yes -video_encoder | yes -manifest_version | yes - -To use those fields that would create a new application version on application update, the server requires `application_partial_updates` extension. - -#### DELETE - * Description: Remove an application - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP application removal case, a JSON format payload input is required from the client: - -```Payload -{ - "force": false // (boolean) Forcibly remove the application -} -``` - -Example -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key --data "$payload" /1.0/applications/my-app -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/d0792e48-a65b-4dcd-87d3-90597f84f964", - "error_code": 0, - "error": "", - "metadata": { - "id": "d0792e48-a65b-4dcd-87d3-90597f84f964", - "class": "task", - "description": "Deleting application", - "created_at": "2018-07-27T06:36:04.370952371Z", - "updated_at": "2018-07-27T06:36:04.370952371Z", - "status": "Running", - "status_code": 103, - "resources": { - "applications": [ - "/1.0/applications/my-app" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of an application removal operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/applications//` - -#### GET - * Description: Export an application version image - * Authentication: trusted - * Operation: sync - * Cancellable: no - * Extension: application_image_export - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/applications/my-app --output app-version.tar -``` -As a result, an application image that contains a piece of `metadata.yaml` and RootFS will be generated - -#### DELETE - * Description: Removes an application version - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP application version removal case, a JSON format payload input is required from client: - -```json -{ - "force": false // (boolean) Forcibly remove the application version -} -``` - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key --data "$payload" \/1.0/applications/my-app/1 -``` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/e0d15285-cef5-4263-bcc4-f1a737a5018e", - "error_code": 0, - "error": "", - "metadata": { - "id": "e0d15285-cef5-4263-bcc4-f1a737a5018e", - "class": "task", - "description": "Delete application version", - "created_at": "2018-07-27T07:17:08.222268495Z", - "updated_at": "2018-07-27T07:17:08.222268495Z", - "status": "Running", - "status_code": 103, - "resources": { - "applications": [ - "/1.0/applications/my-app", - "/1.0/applications/1" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of an application version removal operation, please refer to [`/1.0/operations`](#heading--10operations) - -#### PATCH - * Description: Publish/unpublish an application version - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP application version update case, a JSON format payload input is required from the client: - -```json -{ - "published": true // (boolean) Toggle application publication status -} -``` - -Example: -```bash -curl -s -X PATCH --insecure --cert client.crt --key client.key --data "$payload" \/1.0/applications/my-app/1 -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/157aa633-2cf1-41d6-a8a6-92ecc1830e32", - "error_code": 0, - "error": "", - "metadata": { - "id": "157aa633-2cf1-41d6-a8a6-92ecc1830e32", - "class": "task", - "description": "Updating application version", - "created_at": "2018-07-27T07:35:31.289933915Z", - "updated_at": "2018-07-27T07:35:31.289933915Z", - "status": "Running", - "status_code": 103, - "resources": { - "applications": [ - "/1.0/applications/my-app" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an application version update operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/applications//manifest` - -#### GET - * Description: Get latest application manifest file - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/applications/my-app/manifest -``` - -Output: -```yaml -name: my-app -image: Android10 -instance-type: a4.3 -boot-package: com.lolo.io.onelist -video-encoder: gpu-preferred -watchdog: - disabled: false - allowed-packages: [] -abi: x86_64 -``` -The use of this API requires the `application_manifest_download` extension is supported by the server. - - -### `/1.0/applications///manifest` - -#### GET - * Description: Get one specific application version manifest file - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/applications/my-app/0/manifest -``` - -Output: -```yaml -name: my-app -image: Android10 -instance-type: a4.3 -boot-package: com.lolo.io.onelist -video-encoder: gpu-preferred -watchdog: - disabled: false - allowed-packages: [] -abi: x86_64 -``` -The use of this API requires the `application_manifest_download` extension is supported by the server. - - -### `/1.0/certificates` -#### GET - * Description: List of trusted client certificates - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/certificates -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - "/1.0/certificates/", - ] -} -``` - -#### POST - * Description: Registers a new client certificate as trusted - * Authentication: trusted - * Operation: sync - * Cancellable: no - -In the HTTP certificate removal case, a JSON format payload is required sent by the client: - -```json -{ - "certificate": "MIIFUTCCAzmgAw...xjKoUEEQOzJ9", # Base64 certificate content without header and footer - "trust-password": "aahhdjiks9", # Only needed if not using an already trusted client - # certificate in the SSL request or using the local unix socket -} -``` - -Example: -```bash -curl -s -X POST --insecure --cert client.crt --key client.key --data "$payload" /1.0/certificates -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": null -} -``` - - -### `/1.0/certificates/` -#### GET - * Description: Retrieve information about a stored certificate - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/certificates/ -``` - -Output: - -```json -{ - "certificate": "-----BEGIN CERTIFICATE----- -MIIFUTCCAzmgAw -... -xjKoUEEQOzJ9 ------END CERTIFICATE-----", # Base64 certificate content, including header and footer - "fingerprint": "" -} -``` - -#### DELETE - * Description: Remove specified certificate from the trusted store - * Authentication: trusted - * Operation: async - * Cancellable: no - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key /1.0/certificates/ -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/469f1838-3f10-43cb-97e4-41f49627cf36", - "error_code": 0, - "error": "", - "metadata": { - "id": "469f1838-3f10-43cb-97e4-41f49627cf36", - "class": "task", - "description": "Deleting certificate", - "created_at": "2018-07-27T12:30:54.65841646Z", - "updated_at": "2018-07-27T12:30:54.65841646Z", - "status": "Running", - "status_code": 103, - "resources": { - "certificates": [ - "/1.0/certificates/" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of a certificate removal operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/config` -#### GET - * Description: Retrieve list of all configuration items - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/config -``` -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "config": { - "application.addons": "", // (comma separated list) Addons that will be attached to every application - "application.auto_publish": true, // (true/false) Auto publish application when they are created - "application.default_abi": "", // Default application ABI, would be an ABI with cluster compatible if unset - "application.max_published_versions": 3, // (number) Limit the number of stored application versions - "container.default_platform": "", // (string) Default platform to launch containers with. The `null` platform will be used if unset - "container.features": "", // Features to apply when launching a container - "container.security_updates": false, // Apply security updates when boostraping an applicaiton - "core.proxy_http": "", // HTTP proxy for AMS service - "core.proxy_https": "", // HTTPS proxy for AMS service - "core.proxy_ignore_hosts": "", // Hosts to be ignored in the network proxy - "core.trust_password": true, // Password to be used by the untrusted client to talk to AMS - "gpu.allocation_mode": "all", // GPU allocation mode, optional values: "one" or "all" - "gpu.type": "none", // GPU type, optional values: "none", "nvidia", "intel" or "amd" - "images.allow_insecure": false, // (true/false) Allow an insecure image server - "images.auth": true, // Authentication token for security purpose, `true` implies an auth token has been set, vice versa. - "images.update_interval": "5m", // (time) Frequency of updates from image server - "images.url": "https://images.anbox-cloud.io/stable/", // (string) URL for image server - "images.version_lockstep": "true", // Prevent images of new minor releases to be pulled by AMS - "registry.filter": "", // (comma separated list) Filter out applications without matching tags - "registry.fingerprint": , // (string) Fingerprint of registry certificate - "registry.mode": "pull", // (pull/push/manual) Whether AMS should act as a client or publisher automatically synchronizing applications with AAR, or manually doing so. Please refer to https://anbox-cloud.io/docs/explanation/aar for all details. - "registry.update_interval": "5s", // (time) Frequency of updates from registry - "registry.url": "https://127.0.0.1:3000", // (string) URL of Anbox Application Registry - "scheduler.strategy": "spread" // (spread|binpack) Container allocation schedule strategery - } - } -} -``` - -#### PATCH - * Description: Modify one specific configuration item - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP configuration modification case, a JSON format payload is required sent by the client: - -```json - -{ -"name": "application.auto_publish", -"value": "false" -} -``` - -Example: -```bash -curl -s -X PATCH --insecure --cert client.crt --key client.key --data "$payload" /1.0/config -``` -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/5f2b3817-ada1-43d3-9ed0-0c9ed3a4a20e", - "error_code": 0, - "error": "", - "metadata": { - "id": "5f2b3817-ada1-43d3-9ed0-0c9ed3a4a20e", - "class": "task", - "description": "Applying configuration", - "created_at": "2018-07-27T12:59:14.889009796Z", - "updated_at": "2018-07-27T12:59:14.889009796Z", - "status": "Running", - "status_code": 103, - "resources": null, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` - -To monitor the status of a configuration modification operation, please refer to [`/1.0/operations`](#heading--10operations) - - - -### `/1.0/containers` -#### GET - * Description: Retrieve list of all available containers - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/containers -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - "/1.0/containers/c00i2s0j1qm4f18jdkfg" - ] -} -``` - -#### POST - * Description: Launch a new container - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP container launch case, a JSON format payload is required sent by the client: -Payload: - - * Payload to launch a container from an application -```json -{ - "app_id": "my-app", # (string | mandatory) Identifier or name of the application this container belongs to. - "app_version": 0, # (number | optional) Version of the application this container uses. - "user_data": "", # (string | optional) Additional data to be put into the container when bootstrapped. - "node": "lxd1", # (string | optional) Lxd node to use for the container to launch - "services": [ # (array | optional) List of services the container provides - { - "name": "ssh", # (string) Name of service - "port": 22, # (number) Network port the service listens on - "protocols": ["tcp"], # (array) Network protocol the services uses (udp, tcp) - "expose": false # (boolean) to expose the service on the public endpoint or false to keep it on the private one - } - ], - "disk_size": 5368709120, # (number | optional) Number of bytes disk size to be assigned for the container. - "cpu": 2, # (number | optional) Number of CPU cores to be assigned for the container, - "memory": 4294965097, # (number | optional) Number of bytes memory to be assigned for the container. - "gpu_slots": 0, # (number | optional) Number of GPU slots to be allocated for the container to use - "config": { # (struct | optional) Config parameters included in created container - "platform": "null", # (string | optional) Platform name, optional value: "null", "swrast", "webrtc". Please refer to https://anbox-cloud.io/docs/reference/anbox-platforms for all details of each platform - "boot_package": "com.my.app", # (string | optional) Boot package - "boot_activity": "com.my.app.Activity", # (string | optional) Boot acitivty - "metrics_server": "influxdb:192.168.100.8:8095,raw", # (string | optional) Metrics server - "disable_watchdog": false # (boolean | optional) Toggle watchdog settings - } -} -``` - -* Payload to launch a container from an image -```json -{ - "image_id": "Android_10", # (string | mandatory) Identifier or name of the application this container belongs to. - "instance_type": "a4.3", # (string | mandatory) Instance type to use for the container. Please refer to https://anbox-cloud.io/docs/manage/instance-types-reference for all available instance types. - "image_version": 0, # (number | optional) Version of the image this container uses. - "user_data": "", # (string | optional) Additional data to be put into the container when bootstrapped. - "node": "lxd1", # (string | optional) Lxd node to use for the container to launch - "services": [ # (array | optional) List of services the container provides - { - "name": "ssh", # (string) Name of service - "port": 22, # (number) Network port the service listens on - "protocols": ["tcp"], # (array) Network protocol the services uses (udp, tcp) - "expose": false # (boolean) to expose the service on the public endpoint or false to keep it on the private one - } - ], - "disk_size": 5368709120, # (number | optional) Number of bytes disk size to be assigned for the container. - "cpu": 2, # (number | optional) Number of CPU cores to be assigned for the container, - "memory": 4294965097, # (number | optional) Number of bytes memory to be assigned for the container. - "gpu_slots": 0, # (number | optional) Number of GPU slots to be allocated for the container to use - "config": { # (struct | optional) Config parameters included in created container - "platform": "null", # (string | optional) Platform name, optional value: "null", "swrast", "webrtc". Please refer to https://anbox-cloud.io/docs/reference/anbox-platforms for all details of each platform - "boot_package": "com.my.app", # (string | optional) Boot package - "boot_activity": "com.my.app.Activity", # (string | optional) Boot acitivty - "metrics_server": "influxdb:192.168.100.8:8095,raw" # (string | optional) Metrics server - } -} -``` - -Example: -```bash -curl -s -X POST --insecure --cert client.crt --key client.key --data "$payload" /1.0/containers -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/84767004-de24-4f57-86c3-a0c765487c08", - "error_code": 0, - "error": "", - "metadata": { - "id": "84767004-de24-4f57-86c3-a0c765487c08", - "class": "task", - "description": "Creating container", - "created_at": "2018-07-27T16:06:44.331686878Z", - "updated_at": "2018-07-27T16:06:44.331686878Z", - "status": "Running", - "status_code": 103, - "resources": { - "containers": [ - "/1.0/containers/c08ov50j1qm6t2783d7g" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of a container creation operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/containers/` -#### GET - * Description: Container information - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/containers/ -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "id": "c08p730j1qm6t2783da0", - "name": "ams-c08p730j1qm6t2783da0", - "type": "regular", - "status_code": 4, - "status": "running", - "node": "lxd1", - "app_id": "", - "app_version": 0, - "image_id": "btc5bugj1qm4a9s22580", - "image_version": 0, - "created_at": 1611764620, - "address": "192.168.100.3", - "public_address": "10.226.4.52", - "services": [ - { - "port": 22, - "node_port": 10000, - "protocols": [ - "tcp" - ], - "expose": false, - "name": "ssh" - } - ], - "stored_logs": null, - "error_message": "", - "config": { - "platform": "null", - "boot_package": "com.my.app", - "boot_activity": "com.my.app.Activity", - "metrics_server": "influxdb:192.168.100.8:8095,raw" - }, - "resources": { - "memory": "4GB" - }, - "architecture": "x86_64" - } -} -``` - -#### DELETE - * Description: remove the container - * Authentication: trusted - * Operation: async - * Cancellable: no - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key /1.0/containers/ -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/07ca938d-4d80-47a7-ad1f-18bbaa61ffdc", - "error_code": 0, - "error": "", - "metadata": { - "id": "07ca938d-4d80-47a7-ad1f-18bbaa61ffdc", - "class": "task", - "description": "Deleting container", - "created_at": "2018-07-28T04:44:24.03707954Z", - "updated_at": "2018-07-28T04:44:24.03707954Z", - "status": "Running", - "status_code": 103, - "resources": { - "containers": [ - "/1.0/containers/c08p730j1qm6t2783da0" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of a container removal operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/containers//logs` -#### GET - * Description: List of container logs - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/containers/c00hvbgj1qm4f18jdkb0/logs -``` - -Output: -``` -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - "/1.0/containers/c00hvbgj1qm4f18jdkb0/logs/android.log", - "/1.0/containers/c00hvbgj1qm4f18jdkb0/logs/console.log", - "/1.0/containers/c00hvbgj1qm4f18jdkb0/logs/container.log", - "/1.0/containers/c00hvbgj1qm4f18jdkb0/logs/system.log" - ] -} -``` - - -### `/1.0/containers//logs/` -#### GET - * Description: Retrieves a stored log file for a container - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/containers/c00hvbgj1qm4f18jdkb0/logs/android.log -``` - -Output: -``` ---------- beginning of main -01-28 07:22:44.573 5 5 I : debuggerd: starting ---------- beginning of system -01-28 07:22:44.578 7 7 I vold : Vold 3.0 (the awakening) firing up -01-28 07:22:44.578 7 7 V vold : Detected support for: ext4 vfat -... -``` - - -### `/1.0/events` -This URL isn't a real REST API endpoint, instead of doing a GET query on it -will upgrade the connection to a web socket on which notifications will -be sent. - -#### GET - * Description: web socket upgrade - * Authentication: trusted - * Operation: sync - * Cancellable: no - -URL parameter | Description | Optional values -----------------|-------------------|----------------- -type | comma separated list of notifications to subscribe to (defaults to all) | `operation`, `logging`, `lifecycle` - -The notification types are: - - * `operation` - notification about creation, updates and termination of all background operations - * `logging` - every log entry from the server - * `lifecycle` - container life cycle events - -As a result, this API call upgrades the connection to a web socket on which notifications will be sent. - -This never returns. Each notification is sent as a separate JSON dict, for example: - -```json -{ - "metadata": { // Event metadata - "class": "task", - "created_at": "2017-07-28T05:02:22.92201407Z", - "description": "Deleting container", - "err": "", - "id": "bc85137b-b20d-470a-a6ea-daa9a2b8506a", - "may_cancel": false, - "metadata": null, - "resources": { - "containers": [ - "/1.0/containers/c0946voj1qm6t2783db0" - ] - }, - "server_address": "", - "status": "Success", - "status_code": 200, - "updated_at": "2017-07-28T05:02:22.92201407Z" - }, - "timestamp": "2017-07-28T05:02:22.92201407Z", // Current timestamp - "type": "operation" // Notification type -} -``` - - -### `/1.0/images` -#### GET - * Description: List available images - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/images -``` - -Return value: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - "/1.0/images/btavtegj1qm58qg7ru50" - ] -} -``` - -#### POST - * Description: Registers a new image - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP payload upload case, the following headers may be set by the client: - -* `Content-Type:`: application/octet-stream (mandatory field) -* `X-AMS-Request`: JSON format metadata (mandatory field) -* `X-AMS-Fingerprint:`: SHA-256 (if set, the uploaded payload must match) - -For an image upload, the `X-AMS-Request` header is comprised of: - -``` -{ - "name": "my-image", // (string) Image name - "default": false // (boolean) Whether the default image to be used by AMS -} -``` - -The payload to upload must be a tarball compressed with gzip, bzip2 or xz. It must contain a piece of `metadata.yaml` and RootFS for image registration. - -Example: -```bash -curl -s --header "Content-Type: application/octet-stream" --header 'X-AMS-Request: {"name": "my-image", "default": false}' -X POST --insecure --cert client.crt --key client.key --data-binary @my-image.tar.xz /1.0/images -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/dcdc6eb7-324c-4034-8d86-9f658c5dd696", - "error_code": 0, - "error": "", - "metadata": { - "id": "dcdc6eb7-324c-4034-8d86-9f658c5dd696", - "class": "task", - "description": "Adding image", - "created_at": "2018-07-28T07:48:01.449542378Z", - "updated_at": "2018-07-28T07:48:01.449542378Z", - "status": "Running", - "status_code": 103, - "resources": { - "images": [ - "/1.0/images/c096oc8j1qm30f20g2sg" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an image registration operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/images/` -#### GET - * Description: Load image information - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/images/my-image -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "id": "btbfutoj1qm45810otr0", - "name": "my-image", - "versions": [ - { - "version": 0, - "fingerprint": "0791cfc011f67c60b7bd0f852ddb686b79fa46083d9d43ef9845c9235c67b261", - "size": 529887868, - "created_at": 1610641117, - "status_code": 3, - "status": "active", - "remote_id": "" - } - ], - "status_code": 3, - "status": "active", - "used_by": null, - "immutable": true, - "default": false, - "architecture": "x86_64" - } -} -``` - -#### PATCH (ETag supported) - * Description: Updates an existing image - * Authentication: trusted - * Operation: sync - * Cancellable: no - -An image can be updated with either a new package or specific fields. -The `Content-Type` header of HTTP patch request is different when uploading -an image in either way. - -|Update methods|Content-Type| -| --- | --- | -|With a new package|`application/octet-stream`| -|With specified fields|`application/json`| - -An image package can be uploaded with one of the supported compress format payload(gzip, bzip2 or xz) if the former approach is taken. And X-AMS-Request header is comprised of as follows in this case: - -```json -{ - "name": "my-image", // (string) Image name - "default": false // (boolean) Default image setting -} -``` - -Example: -```bash -curl -s --header "Content-Type: application/octet-stream" --header 'X-AMS-Request: {"name": "my-image", "default": false}' -X PATCH --insecure --cert client.crt --key client.key --data-binary @my-image.tar.bz2 /1.0/images/my-image -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/882795ad-6876-46b2-8f32-8226f4b22912", - "error_code": 0, - "error": "", - "metadata": { - "id": "882795ad-6876-46b2-8f32-8226f4b22912", - "class": "task", - "description": "Updating image", - "created_at": "2018-07-28T08:23:14.253985803Z", - "updated_at": "2018-07-28T08:23:14.253985803Z", - "status": "Running", - "status_code": 103, - "resources": { - "images": [ - "/1.0/images/my-image" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -As a result, a new image version will be generated. - -To update an image with a specified field, a JSON format payload is accepted. - -```json -{ - "default": true // (boolean) Default image setting -} -``` -URL parameter | Description | Optional values -----------------|-------------------|----------------- -type | comma separated list of notifications to subscribe to (defaults to all) | `operation`, `logging`, `lifecycle` -Example: -```bash -curl -s --header "Content-Type: application/json" -X PATCH --insecure --cert client.crt --key client.key --data "$payload" /1.0/images/my-image -``` - -When updating an image with the above field, no new image version will be generated. - -To monitor the status of an image update operation, please refer to [`/1.0/operations`](#heading--10operations) - -#### DELETE - * Description: Remove an existing image - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP image removal case, a JSON format payload input is required from the client: - -```Payload -{ - "force": false // (boolean) Forcibly remove the image -} -``` - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key --data "$payload" /1.0/images/my-image -``` - -Output: -```json -`{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/5485e9ea-bd57-48f1-af0d-761056c7d4e0", - "error_code": 0, - "error": "", - "metadata": { - "id": "5485e9ea-bd57-48f1-af0d-761056c7d4e0", - "class": "task", - "description": "Deleting image", - "created_at": "2018-07-28T10:29:16.26129557Z", - "updated_at": "2018-07-28T10:29:16.26129557Z", - "status": "Running", - "status_code": 103, - "resources": { - "images": [ - "/1.0/images/c098kfgj1qm5ivqf9ktg" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an image removal operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/images//` -#### DELETE - * Description: Deletes a single version of an image - * Authentication: trusted - * Operation: async - * Cancellable: no - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key /1.0/images/my-image/2 -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/412e428d-7468-454b-aef8-b29540d1960d", - "error_code": 0, - "error": "", - "metadata": { - "id": "412e428d-7468-454b-aef8-b29540d1960d", - "class": "task", - "description": "Deleting image version", - "created_at": "2018-07-28T10:18:55.938675833Z", - "updated_at": "2018-07-28T10:18:55.938675833Z", - "status": "Running", - "status_code": 103, - "resources": { - "images": [ - "/1.0/images/my-image" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an image version removal operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/nodes` -#### GET - * Description: List available nodes - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/nodes -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - { - "name": "lxd1", - "address": "10.226.4.52", - "public_address": "10.226.4.52", - "network_bridge_mtu": 1500, - "cpus": 2, - "cpu_allocation_rate": 4, - "memory": "3GB", - "memory_allocation_rate": 2, - "status_code": 4, - "status": "online", - "is_master": true, - "disk_size": "21GB", - "gpu_slots": 0, - "gpu_encoder_slots": 0, - "tags": [], - "unschedulable": false, - "architecture": "x86_64", - "storage_pool": "ams0", - "managed": true - } - ] -} -``` - -#### POST - * Description: Add a LXD node to the cluster - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP node registration case, a JSON format payload input is required from the client: - -```json -{ - "name": "lxd2", // (string | mandatory) Name to the LXD node to be added to AMS - "address": "172.31.23.150", // (string | mandatory) LXD node address - "public_address": "34.250.180.153", // (string | optional) LXD node public address - "trust_password": "foobar", // (string | optional) Trust password for the remote LXD node - "network_bridge_mtu": 1500, // (number | optional) MTU of the network bridge configured for LXD - "storage_device": "/dev/sda", // (string | optional) Storage device LXD node should use - "cpus": 32 // (number | optional) (number | optional) Number of CPU cores used by LXD node - "cpu_allocation_rate": 4, // (number | optional) Factor of CPU overcommitment. Overcommitting resources allow to run more containers per node - "memory": "256GB", // (string | optional) Memory used by LXD node - "memory_allocation_rate": 2, // (number | optional) Factor of memory overcommitment. Similar to cpu-allocation rate - "gpu_slots": 10, // (number | optional) Slots on the GPU available to containers - "gpu_encoder_slots": 10, // (number | optional) Slots on the GPU encoders available to containers - "tags": [], // (array | optional) User defined tags - "unmanaged": false, // (boolean | optional) Expect node to be already clustered - "storage_pool": "", // (string | optional) Existing LXD storage pool to use - "network_name": "amsbr0", // (string | optional) Name of the network device to create on the LXD cluster. Default to "amsbr0" if unet - "network_subnet": "192.168.100.1/24" // (string | optional) Network subnet for the network device on the node. Default to "192.168.100.1/24" if unset -} -``` - -Example: -```bash -curl -s -X POST --insecure --cert client.crt --key client.key --data "$payload" /1.0/nodes -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/2215b63c-9f2b-4665-bf34-6fe8dbcbe4b5", - "error_code": 0, - "error": "", - "metadata": { - "id": "2215b63c-9f2b-4665-bf34-6fe8dbcbe4b5", - "class": "task", - "description": "Creating node", - "created_at": "2018-07-28T11:51:13.261045632Z", - "updated_at": "2018-07-28T11:51:13.261045632Z", - "status": "Running", - "status_code": 103, - "resources": { - "nodes": [ - "/1.0/nodes/lxd2" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an LXD node registration operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/nodes/` -#### GET - * Description: Load node information - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/nodes/lxd1 -``` -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "name": "lxd1", - "address": "10.226.4.52", - "public_address": "10.226.4.52", - "network_bridge_mtu": 1500, - "cpus": 2, - "cpu_allocation_rate": 4, - "memory": "3GB", - "memory_allocation_rate": 2, - "status_code": 4, - "status": "online", - "is_master": false, - "disk_size": "21GB", - "gpu_slots": 0, - "gpu_encoder_slots": 0, - "tags": [], - "unschedulable": false, - "architecture": "x86_64", - "storage_pool": "ams0", - "managed": true - } -} -``` - -#### PATCH (ETag supported) - * Description: Update node configuration - * Authentication: trusted - * Operation: sync - * Cancellable: no - -In the HTTP node update case, a JSON format payload input is required from the client: - -Supported update field | Description ------------------|------------------------------------ -`public_address` | (string) LXD node public address -`cpus` | (number) Number of CPU cores used by LXD node -`cpu_allocation_rate` | (number) Factor of CPU overcommitment. Overcommitting resources allow to run more containers per node -`memory` | (string) Memory used by LXD node -`memory_allocation_rate` | Factor of memory overcommitment. -`gpu_slots` | (number) Slots on the GPU available to containers -`gpu_encoder_slots` | (number) Slots on the GPU encoders available to containers -`tags` | (string) User defined tags -`unschedulable` | (Boolean) Whether this LXD node is schedulable by AMS. - -A sample payload as follows: - -```json -{ - "cpu_allocation_rate": 4, - "memory_allocation_rate": 2 -} -``` - -Example: -```bash -curl -s -X PATCH --insecure --cert client.crt --key client.key --data "$payload"/1.0/nodes/lxd0 -`` - -Output: - -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/a6124977-72c2-4daa-b349-8e31e12dfd37", - "error_code": 0, - "error": "", - "metadata": { - "id": "a6124977-72c2-4daa-b349-8e31e12dfd37", - "class": "task", - "description": "Updating node lxd1", - "created_at": "2018-07-28T13:04:04.701576609Z", - "updated_at": "2018-07-28T13:04:04.701576609Z", - "status": "Running", - "status_code": 103, - "resources": { - "nodes": [ - "/1.0/nodes/lxd1" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of an LXD node update operation, please refer to [`/1.0/operations`](#heading--10operations) - -#### DELETE - * Description: Remove the node from the cluster - * Authentication: trusted - * Operation: async - * Cancellable: no - -In the HTTP node removal case, a JSON format payload input is required from the client: - -```json -{ - "force": false, // (boolean) Forcibly remove the node - "keep_in_cluster": false // (boolean) Whether to remove the node from LXD cluster as well -} -``` - -Example: -```bash -curl -s -X DELETE --insecure --cert client.crt --key client.key --data "$payload"/1.0/nodes/lxd0 -``` - -Output: -```json -{ - "type": "async", - "status": "Operation created", - "status_code": 100, - "operation": "1.0/operations/cc43bc37-330a-4696-b3f4-b7639b05ae8a", - "error_code": 0, - "error": "", - "metadata": { - "id": "cc43bc37-330a-4696-b3f4-b7639b05ae8a", - "class": "task", - "description": "Deleting node", - "created_at": "2018-07-28T10:56:18.912988425Z", - "updated_at": "2018-07-28T10:56:18.912988425Z", - "status": "Running", - "status_code": 103, - "resources": { - "nodes": [ - "/1.0/nodes/lxd0" - ] - }, - "metadata": null, - "may_cancel": true, - "err": "", - "server_address": "" - } -} -``` -To monitor the status of a LXD node removal operation, please refer to [`/1.0/operations`](#heading--10operations) - - -### `/1.0/operations` -#### GET - * Description: list of operations - * Authentication: trusted - * Operation: sync - * Return: list of URLs for operations that are currently going on/queued - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/operations -``` - -Output: -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "success": [ - "1.0/operations/5d2a6807-7c8a-48eb-94c7-e07dd75119ce" - ] - } -} -``` - - -### `/1.0/operations/` -#### GET - * Description: Load operation information. If the service is deployed as -a cluster of several instances, the operation is held in one of them. In -case the request reaches a different instance of the one holding the -operation, the information is taken internally from the right one. - * Authentication: trusted - * Operation: sync - * Cancellable: no - -For example, when changing the publication status of an application by issuing -```bash -payload='{"published": false}' -operation=$(curl -s -X PATCH --insecure --cert client.crt --key client.key --data "$payload" /1.0/applications/my-app/0 | jq -r .operation) -``` - -To monitor the operation status -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /$operation | jq . - -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "id": "0db09aee-3de9-4250-b707-0a3a90fd39c6", - "class": "task", - "description": "Updating application version", - "created_at": "2018-07-28T13:25:35.186064229Z", - "updated_at": "2018-07-28T13:25:35.186064229Z", - "status": "Success", - "status_code": 200, - "resources": { - "applications": [ - "/1.0/applications/my-app" - ] - }, - "metadata": null, - "may_cancel": false, - "err": "", - "server_address": "" - } -} -``` - -#### DELETE - * Description: Cancel an operation. Calling this will change the state of cancellable API to "cancelling" rather than actually removing the entry. If the service is deployed as a cluster of several instances, the operation is held in one of them. In case the request reaches a different instance of the one holding the -operation, the information is taken internally from the right one. - * Authentication: trusted - * Operation: sync - * Cancellable: no - -For example, to cancel an operation of an application creation -```bash -operation=$(curl -s --header "Content-Type: application/octet-stream" -X POST ---insecure --cert client.crt --key client.key --data-binary @my-app.tar.bz2 - /1.0/applications | jq -r .operation) - -curl -s -X DELETE --insecure --cert client.crt --key client.key /$operation| jq . -``` - -Output: -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": {} -} -``` - -HTTP code for this should be 202 (Accepted). - - -### `/1.0/operations//wait` -#### GET - * Description: Wait until an operation reaches a final status - * Authentication: trusted - * Operation: sync - * Cancellable: yes - -URL parameter | Description -----------------|------------------- -timeout | The amount of time (In second) when wait operation reaches timed out. If the value is assigned to `-1`, it means the operation will wait infinitely until the monitored operation reaches a final status. - -For example, to wait for the process of an application creation to be done -```bash -operation=$(curl -s --header "Content-Type: application/octet-stream" -X POST ---insecure --cert client.crt --key client.key --data-binary @my-app.tar.bz2 - /1.0/applications | jq -r .operation) - -curl -s -X GET \ - --insecure --cert ~/trust-client/client.crt --key ~/trust-client/client.key \ - /$operation/wait | jq . -``` - -Output: -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "id": "fbe40515-7948-41c8-8668-e815db8916f8", - "class": "task", - "description": "Creating application", - "created_at": "2018-07-28T13:39:49.736209814Z", - "updated_at": "2018-07-28T13:39:49.736209814Z", - "status": "Success", - "status_code": 200, - "resources": { - "applications": [ - "/1.0/applications/c09bt98j1qm1as2tvn00" - ] - }, - "metadata": null, - "may_cancel": false, - "err": "", - "server_address": "" - } -} -``` - - -### `/1.0/operations//websocket` -#### GET (`?secret=SECRET`) - * Description: This connection is upgraded into a web socket connection - speaking the protocol defined by the operation type. For example, in the - case of an exec operation, the web socket is the bidirectional pipe for - stdin/stdout/stderr to flow to and from the process inside the container. - In the case of migration, it will be the primary interface over which the - migration information is communicated. The secret here is the one that was - provided when the operation was created. Guests are allowed to connect - provided they have the right secret. - * Authentication: guest or trusted - * Operation: sync - * Cancellable: no - - -### `/1.0/tasks` -#### GET - * Description: List of available tasks - * Authentication: trusted - * Operation: sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/tasks -``` - - Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": [ - { - "id": "c055dl0j1qm027422feg", - "status": "running", - "object_id": "c055dl0j1qm027422fe0", - "object_type": "container" - } - ] -} -``` - - -### `/1.0/version` -#### GET - * Description: Load status information about the service - * Authentication: guest - * Operation: Sync - * Cancellable: no - -Example: -```bash -curl -s -X GET --insecure --cert client.crt --key client.key /1.0/version -``` - -Output: - -```json -{ - "type": "sync", - "status": "Success", - "status_code": 200, - "operation": "", - "error_code": 0, - "error": "", - "metadata": { - "version": "1.7.3" - } -} -``` diff --git a/reference/anbox-features.md b/reference/anbox-features.md index 50756444..7cd9d5d4 100644 --- a/reference/anbox-features.md +++ b/reference/anbox-features.md @@ -1,15 +1,18 @@ +(ref-aosp-aaos)= +# Supported features for AOSP vs AAOS images + Anbox Cloud provides images based on the Android Open Source Project (AOSP), an operating system typically used in mobile devices or an Anbox Cloud AAOS image which is based on the Android Automotive OS (AAOS), an infotainment platform used in automobiles. Supported Anbox features differ depending what a given image is based on. The following table lists some Anbox features and whether they are supported for a given base. -| Feature | AOSP | AAOS | -|---------------------------------------------------------------------------------------------------------------------|------|------| -| boot-package and boot-activity in [application manifest](https://discourse.ubuntu.com/t/application-manifest/24197) | ✓ | - | -| [Install app as system app](https://discourse.ubuntu.com/t/how-to-install-an-apk-as-a-system-app/27086) | ✓ | - | -| [Custom Android ID](https://discourse.ubuntu.com/t/ams-configuration/20872#custom-android-id-10) | ✓ | - | -| [VHAL HTTP API](https://discourse.ubuntu.com/t/anbox-http-api/17819#h-10vhal-31) | - | ✓ | -| [VhalConnector](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/classanbox_1_1VhalConnector.html) in Platform SDK API | - | ✓ | -| [Custom images](https://discourse.ubuntu.com/t/custom-images/45071) | - | ✓ | | | ✓ | +|Feature | AOSP | AAOS | +|--------|------|------| +| boot-package and boot-activity in {ref}`ref-application-manifest` | ✓ | - | +| {ref}`howto-install-apk-system-app` | ✓ | - | +| [Custom Android ID](#custom-android-id) | ✓ | - | +| {ref}`VHAL HTTP API ` | - | ✓ | +| [VhalConnector](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/classanbox_1_1VhalConnector.html) in Platform SDK API | - | ✓ | +| {ref}`exp-custom-images` | - | ✓ | ## Feature flags @@ -42,15 +45,15 @@ The feature flag will be considered by all new launched instances once set. The Android virtual keyboard is disabled by default but can be enabled with the `enable_virtual_keyboard` feature flag. -For the feature to be considered, applications must be manually updated, because changes to allow the feature to work are only applied during the [application bootstrap process](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2). +For the feature to be considered, applications must be manually updated, because changes to allow the feature to work are only applied during the application {ref}`bootstrap process `. ### Client-Side Virtual Keyboard *since 1.11.0* -The client-side virtual keyboard is disabled by default but can be enabled with the `enable_anbox_ime` feature flag. It requires the client application to embed [Anbox WebView](https://discourse.ubuntu.com/t/integrate-a-client-side-virtual-keyboard/23643) which interacts with the client-side virtual keyboard for text editing and sends the text to the Android container. +The client-side virtual keyboard is disabled by default but can be enabled with the `enable_anbox_ime` feature flag. It requires the client application to embed {ref}`Anbox WebView ` which interacts with the client-side virtual keyboard for text editing and sends the text to the Android container. -For the feature to be considered, applications must be manually updated, because changes to allow the feature to work are only applied during the [application bootstrap process](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2). +For the feature to be considered, applications must be manually updated, because changes to allow the feature to work are only applied during the application {ref}`bootstrap process `. ### WiFi @@ -66,7 +69,7 @@ The feature flag will be considered by all newly launched instances once set. By default, Android is not allowed to reboot. With the `allow_android_reboot` feature flag, this can be allowed. -Note that you must disable the [watchdog](https://discourse.ubuntu.com/t/application-manifest/24197#watchdog-5) if reboots are allowed. +Note that you must disable the {ref}`sec-application-manifest-watchdog` if reboots are allowed. The feature flag will be considered by all newly launched instances once set. @@ -93,6 +96,7 @@ To enable the Android container to use a custom Android ID, add the feature flag Once set, this feature flag will be considered by all newly launched instances. +(sec-gl-async-swap)= ### GL Async Swap Support *since 1.21.0* @@ -105,9 +109,9 @@ Once set, this feature flag will be considered by all newly launched instances. *since 1.20.2* -[note type="caution" status="Warning"] +```{caution} Enabling this will print IP addresses of WebRTC clients connecting to the Anbox Cloud instances in the logs without anonymization in clear text. -[/note] +``` For debugging purposes, Anbox Cloud can log ICE candidates from the server and client inside the system log of an instance. This is disabled by default and needs to be explicitly turned on with the feature flag `webrtc.enable_ice_logging`. diff --git a/reference/anbox-https-api.md b/reference/anbox-https-api.md index 2e6d117f..0081d089 100644 --- a/reference/anbox-https-api.md +++ b/reference/anbox-https-api.md @@ -1,4 +1,7 @@ -Anbox Cloud provides an HTTP API endpoint through a Unix socket at `/run/users/1000/anbox/api.socket` inside every [instance](https://discourse.ubuntu.com/t/26204#instance). The API allows controlling certain aspects of the Anbox runtime and the Android container. +(anbox-https-api)= +# Anbox HTTPS API + +Anbox Cloud provides an HTTP API endpoint through a Unix socket at `/run/users/1000/anbox/api.socket` inside every instance. The API allows controlling certain aspects of the Anbox runtime and the Android container. ## Accessing the API endpoint @@ -56,19 +59,19 @@ HTTP code must be one of 400 or 500. ## API structure - * [`/1.0`](#heading--10) - * [`/1.0/location`](#heading--10location) - * [`/1.0/camera`](#heading--10camera) - * [`/1.0/camera/data`](#heading--10cameradata) - * [`/1.0/sensors`](#heading--10sensors) - * [`/1.0/tracing`](#heading--10tracing) - * [`/1.0/platform`](#heading--10platform) - * [`/1.0/vhal`](#heading--10vhal) - * [`/1.0/vhal/config`](#heading--10vhalconfig) + * {ref}`sec-anbox-https-api-1.0` + * {ref}`sec-anbox-https-api-location` + * {ref}`sec-anbox-https-api-camera` + * {ref}`sec-anbox-https-api-cameradata` + * {ref}`sec-anbox-https-api-sensors` + * {ref}`sec-anbox-https-api-tracing` + * {ref}`sec-anbox-https-api-platform` + * {ref}`sec-anbox-https-api-vhal` + * {ref}`sec-anbox-https-api-vhalconfig` ## API details - +(sec-anbox-https-api-1.0)= ### `/1.0/` #### GET @@ -100,7 +103,7 @@ Return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api. } ``` - +(sec-anbox-https-api-location)= ### `/1.0/location` #### GET @@ -108,7 +111,9 @@ Return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api. * Operation: sync * Return: Current location status -[note type="information" status="Note"]After enabling the location endpoint, any location updates provided via the [Anbox Platform API](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/) won't be processed by Anbox until the location endpoint is disabled again.[/note] +```{note} +After enabling the location endpoint, any location updates provided via the [Anbox Platform API](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/) won't be processed by Anbox until the location endpoint is disabled again. +``` Return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api.unix s/1.0/location | jq .`: @@ -129,7 +134,9 @@ Return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api. * Operation: sync * Return: standard return value or standard error -[note type="information" status="Note"]Location updates must be activated before posting any location data to Anbox via the `PATCH` method. If location updates are disabled, requests to provide updates to the Anbox HTTP API will fail.[/note] +```{note} +Location updates must be activated before posting any location data to Anbox via the `PATCH` method. If location updates are disabled, requests to provide updates to the Anbox HTTP API will fail. +``` Return value for `curl -s -X POST --unix-socket /run/user/1000/anbox/sockets/api.unix s/1.0/location --data '{"enable":true}' | jq .`: @@ -140,18 +147,18 @@ Return value for `curl -s -X POST --unix-socket /run/user/1000/anbox/sockets/api "type": "sync" } ``` - + #### PATCH * Description: Provide location update to be forwarded to Android * Operation: sync * Return: standard return value or standard error -[note type="information" status="Note"] +```{note} The latitude or longitude of geographic coordinates can be expressed in [decimal degree](https://en.wikipedia.org/wiki/Decimal_degrees) form (WGS84 data format) as shown below in the example or in an NMEA-based data format as [`ddmm.mm`](https://en.wikipedia.org/wiki/Geographic_coordinate_conversion) (d refers to degrees, m refers to minutes). Specify the format by setting the `format` field to either `"wgs84"` or `"nmea"`. If the field is omitted, its value defaults to `"wgs84"`. No matter which format you use, northern latitudes or eastern longitudes are positive, southern latitudes or western longitudes are negative. Both vertical and horizontal accuracy are measured in meters. The default value for GPS accuracy is 20 meters. -[/note] +``` Input: @@ -179,7 +186,7 @@ Return value: } ``` - +(sec-anbox-https-api-camera)= ### `/1.0/camera` #### GET @@ -233,7 +240,7 @@ To determine if the camera is enabled, run the following query: curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api.unix s/1.0/camera | jq .metadata.enabled - +(sec-anbox-https-api-cameradata)= ### `/1.0/camera/data` #### POST @@ -256,7 +263,9 @@ After this, when opening a camera application, the uploaded image should be disp If a static image already exists in Anbox Cloud, when you issue the above request next time, the existing image will be overridden. -[note type="information" status="Note"]Irrespective of whether the screen orientation is in landscape or portrait, the size of the uploaded JPEG image must match one of the resolutions you got from the response to the camera info request. Anbox Cloud will rotate the image automatically for you based on current screen orientation.[/note] +```{note} +Irrespective of whether the screen orientation is in landscape or portrait, the size of the uploaded JPEG image must match one of the resolutions you got from the response to the camera info request. Anbox Cloud will rotate the image automatically for you based on current screen orientation. +``` #### DELETE @@ -306,7 +315,7 @@ With ffmpeg, you can do: ffmpeg -r 10 -i test.mp4 -vf format=rgba -s 1280x720 -f rawvideo -r 25 - | nc -N -U /run/user/1000/anbox/sockets/camera_video_stream ``` - +(sec-anbox-https-api-sensors)= ### `/1.0/sensors` #### GET @@ -355,7 +364,9 @@ Return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api. * Operation: sync * Return: standard return value or standard error -[note type="information" status="Note"]Sensor updates must be activated before posting any sensor data to Anbox via the `PATCH` method. If sensor updates are disabled, requests to provide updates to the Anbox HTTP API will fail.[/note] +```{note} +Sensor updates must be activated before posting any sensor data to Anbox via the `PATCH` method. If sensor updates are disabled, requests to provide updates to the Anbox HTTP API will fail. +``` Return value for `curl -s -X POST --unix-socket /run/user/1000/anbox/sockets/api.unix s/1.0/sensors --data '{"enable":true}' | jq .`: @@ -400,12 +411,13 @@ Sensor Type | JSON Data structure | Please check the following [link](https://developer.android.com/guide/topics/sensors/sensors_environment) for the units of measure for the environmental sensors. -[note type="information" status="Note"]If Android framework or applications are not requesting sensor data during its runtime, any attempt to send sensor data to Anbox via HTTP API endpoint will fail with the error `Sensor 'acceleration' is not active` even if the sensor updates are activated. +```{note} +If Android framework or applications are not requesting sensor data during its runtime, any attempt to send sensor data to Anbox via HTTP API endpoint will fail with the error `Sensor 'acceleration' is not active` even if the sensor updates are activated. Issuing GET method to sensor endpoint can check the current active sensors in the Android container. -[/note] +``` - +(sec-anbox-https-api-tracing)= ### `/1.0/tracing` #### GET @@ -465,7 +477,7 @@ Return value: As a result, a trace file can be found from the given path recorded in the response. You can pull that file from the instance and import it to [Perfetto Trace Viewer](https://ui.perfetto.dev/#!/viewer) for further analysis. - +(sec-anbox-https-api-platform)= ### `/1.0/platform` #### GET @@ -513,7 +525,7 @@ Platform | Field name | Available since | JSON type | Access | Descripti `webrtc` | `rtc_log` | 1.15 | Boolean | read/write | Enable/disable [RTC event logging](https://webrtc.googlesource.com/src/+/lkgr/logging/g3doc/rtc_event_log.md). Logs are written to `/var/lib/anbox/traces/rtc_log.*` inside the instance. | `webrtc` | `stream_active` | 1.15 | Boolean | read | `true` if a client is actively streaming, `false` if no client is connected. | - +(sec-anbox-https-api-vhal)= ### `/1.0/vhal` This endpoint queries the [Android VHAL](https://source.android.com/docs/automotive/vhal) @@ -531,7 +543,7 @@ endpoint will fail with a 500 error code on non-automotive Anbox images. * `area_id`: Valid area identifier for the property. Can be omitted for global properties. Can be given in decimal, octal, or hexadecimal format. * Some properties require additional data for getting their values. See [OBD2_FREEZE_FRAME](https://cs.android.com/android/platform/superproject/+/android10-release:hardware/interfaces/automotive/vehicle/2.0/types.hal;l=2061-2089) for an example. This additional data must be passed as JSON in the request body. The values must be set in the fields `int32_values`, `int64_values`, `float_values`, `bytes`, or `string_value`. -To get the list of available properties and areas, query first the [`1.0/vhal/config` endpoint](#heading--10vhalconfig). +To get the list of available properties and areas, query first the [`1.0/vhal/config` endpoint](#10vhalconfig). Example return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sockets/api.unix s/1.0/vhal/0x15600503/0x31 | jq .`: @@ -560,7 +572,7 @@ Example return value for `curl -s -X GET --unix-socket /run/user/1000/anbox/sock Usually, only one of `bytes`, `float_values`, `int32_values`, `int64_values`, `string_value` is set, and the rest is empty or omitted, depending on the -property type (see [`1.0/vhal/config`](#heading--10vhalconfig)). +property type (see [`1.0/vhal/config`](#10vhalconfig)). `MIXED` property types may have multiple of these values set at the same time, see [VHAL property types](https://source.android.com/docs/automotive/vhal/property-configuration#property-types). @@ -620,7 +632,7 @@ Return value for the input above: "type": "sync" } ``` - +(sec-anbox-https-api-vhalconfig)= ### `/1.0/vhal/config` This endpoint queries the [Android VHAL](https://source.android.com/docs/automotive/vhal) diff --git a/reference/android-features.md b/reference/android-features.md index 5e2ed642..6897cde0 100644 --- a/reference/android-features.md +++ b/reference/android-features.md @@ -1,3 +1,6 @@ +(ref-android-features)= +# Supported Android features + Anbox Cloud implements support for various Android features. The following table lists certain Android features and if they are supported in Anbox Cloud. | Feature | Supported | Notes | @@ -7,7 +10,7 @@ Anbox Cloud implements support for various Android features. The following table | [Camera](https://source.android.com/devices/camera) | ✓ | | | [Sensors](https://source.android.com/devices/sensors) | ✓ | | | Location | ✓ | | -| [VHAL](https://source.android.com/docs/automotive/vhal) | ✓ | Only on [AAOS images](https://discourse.ubuntu.com/t/provided-images/24185). | +| [VHAL](https://source.android.com/docs/automotive/vhal) | ✓ | Only on AAOS images (See {ref}`ref-provided-images`). | | NFC | | | | [Bluetooth](https://source.android.com/devices/bluetooth) | | | | WiFi | ✓ | Only simulated WiFi is provided to the Android instance. | diff --git a/reference/api-reference.md b/reference/api-reference.md index 337dcbe1..475d382f 100644 --- a/reference/api-reference.md +++ b/reference/api-reference.md @@ -1,3 +1,6 @@ +(ref-api)= +# API reference + All communication between AMS and its clients happen using a RESTful API over HTTP. This API is encapsulated over either TLS (for remote operations) or a Unix socket (for local operations). ## APIs and their structure @@ -9,7 +12,7 @@ Anbox Cloud provides the following APIs: * Stream Gateway API * Anbox Platform SDK API -All these APIs except for the [Anbox Cloud HTTP API](https://discourse.ubuntu.com/t/anbox-http-api/17819) have an auto-generated specification describing its API endpoints. +All these APIs except for the {ref}`anbox-https-api` have an auto-generated specification describing its API endpoints. ## Authentication @@ -186,3 +189,12 @@ Some operations require uploading a payload. To prevent the difficulties of hand The documentation shows paths such as `/1.0/instances/...`, which were introduced with Anbox Cloud version 1.20.0. Older releases that supported only containers and not virtual machines supply the exact same API at `/1.0/containers/...`. Although deprecated, the `1.0/containers/...` API is still available for backward compatibility. + +```{toctree} +:hidden: + +AMS HTTP API +anbox-https-api +Anbox Platform API +Stream gateway API +``` diff --git a/reference/appliance-command-reference/landing.md b/reference/appliance-command-reference/landing.md deleted file mode 100644 index d35d68d5..00000000 --- a/reference/appliance-command-reference/landing.md +++ /dev/null @@ -1,18 +0,0 @@ -The `anbox-cloud-appliance` is a command line client to manage the appliance and its components. - -Use `anbox-cloud-appliance --help` or `anbox-cloud-appliance --help` to display usage information for the tool and its commands. - -The following commands are available for the `anbox-cloud-appliance` tool: - -| Command | Description| -|---------|------------| -|[`ams`](https://discourse.ubuntu.com/t/39517) | Manage access to the Anbox Management Service (AMS)| -|[`dashboard`](https://discourse.ubuntu.com/t/39520)| Manage the web dashboard of appliance| -|[`destroy`](https://discourse.ubuntu.com/t/39521) | Destroy the appliance| -|[`gateway`](https://discourse.ubuntu.com/t/39522) | Manage the appliance stream gateway| -|[`help`](https://discourse.ubuntu.com/t/39523) | Help about the `anbox-cloud-appliance` tool| -|[`init`](https://discourse.ubuntu.com/t/39524)| Initialise the appliance| -|[`status`](https://discourse.ubuntu.com/t/39527) | Display the current status and version of the appliance| -|[`upgrade`](https://discourse.ubuntu.com/t/39528) | Upgrade the appliance to a newer version| - -If you encounter an issue and want to collect debugging information from the appliance, use `anbox-cloud-appliance.buginfo`. diff --git a/reference/application-manifest.md b/reference/application-manifest.md index 9e6615d8..75d620fa 100644 --- a/reference/application-manifest.md +++ b/reference/application-manifest.md @@ -1,3 +1,6 @@ +(ref-application-manifest)= +# Application manifest + An application manifest defines the various attributes of an application. The available attributes are listed in the following table: @@ -6,28 +9,31 @@ Name | Value type | Description | Status | --------------|------------|-------------------------|----| `name` | string | Verbose name of the application. The following special characters are not allowed: `< > : " / \ \| ? *`, as well as space | Supported | `version` | string | Version to encode with the application. Maximum length is 50 characters. | Supported | -`instance-type` | string | Instance type that all [instances](https://discourse.ubuntu.com/t/26204#instance) created for the application will use. [Jump to details](#instance-type-1) | Deprecated since 1.20 | +`instance-type` | string | Instance type that all instances created for the application will use. {ref}`Learn more ` | Deprecated since 1.20 | `required-permissions` | array of strings | List of permissions to automatically grant to the application. See [Android Permissions](https://developer.android.com/guide/topics/permissions/overview) for a list of available permissions. If `[*]` was given, all required runtime permissions for the application will be granted on application installation. | Supported | -`image` (optional) | string | Name or ID of an image to be used for the application. The default image is used if empty. [Jump to details](#image-2) | Supported | +`image` (optional) | string | Name or ID of an image to be used for the application. The default image is used if empty. {ref}`Learn more ` | Supported | `addons` (optional) | array | List of addons to be installed during the application bootstrap process. | Supported | `tags` (optional) | array | List of tags to be associated with the application. | Supported | `boot-package` (optional) | string | Package to launch once the system has booted (default: package name retrieved from the APK if APK file is present). | Supported on AOSP only | `boot-activity` (optional) | string | Activity of boot package to launch once the system has booted (default: main activity as defined in the application manifest). | Supported on AOSP only | -`video-encoder` (optional) | string | Video encoder to be used by an instance launched from the application (default: `gpu-preferred`). Possible values are: `gpu`, `gpu-preferred`, `software`. [Jump to details](#video-encoder-4) | Supported | -`watchdog` (optional) | map | Watchdog settings to be configured on application installation. [Jump to details](#watchdog-5)| Supported | -`services` (optional) | array | Services to be provided from the installed application. [Jump to details](#services-6) | Supported | -`resources` (optional) | map | Resources to be allocated on application installation. [Jump to details](#resources-7) | Supported | -`extra-data` (optional) | array | List of additional data to be installed on application installation. [Jump to details](#extra-data-8) | Supported | -`hooks` (optional) | object | Hooks settings to be configured on application installation. [Jump to details](#hooks-9) | Supported | -`bootstrap` (optional) | object | Application bootstrap settings to be configured on application installation. [Jump to details](#bootstrap-10)| Supported | +`video-encoder` (optional) | string | Video encoder to be used by an instance launched from the application (default: `gpu-preferred`). Possible values are: `gpu`, `gpu-preferred`, `software`. {ref}`Learn more ` | Supported | +`watchdog` (optional) | map | Watchdog settings to be configured on application installation. {ref}`Learn more `| Supported | +`services` (optional) | array | Services to be provided from the installed application. {ref}`Learn more ` | Supported | +`resources` (optional) | map | Resources to be allocated on application installation. {ref}`Learn more ` | Supported | +`extra-data` (optional) | array | List of additional data to be installed on application installation. {ref}`Learn more ` | Supported | +`hooks` (optional) | object | Hooks settings to be configured on application installation. {ref}`Learn more ` | Supported | +`bootstrap` (optional) | object | Application bootstrap settings to be configured on application installation. {ref}`Learn more `| Supported | `features` (optional) | array | List of feature flags to be defined for instances created from the application. | Supported | -`node-selector` (optional) | array | List of selectors which will limit what node an instance for the application can be scheduled on. [Jump to details](#node-selector-3) | Supported | +`node-selector` (optional) | array | List of selectors which will limit what node an instance for the application can be scheduled on. {ref}`Learn more ` | Supported | +(sec-application-manifest-instance-type)= ## Instance type -[note type="information" Status="Note"] The `instance-type` attribute is deprecated since 1.20. For any application, a default set of resources will be chosen. If you wish to set specific resources to your application, use the [`resources` attribute](#resources) to do so. +```{note} +The `instance-type` attribute is deprecated since 1.20. For any application, a default set of resources will be chosen. If you wish to set specific resources to your application, use the [`resources` attribute](#resources) to do so. -When using the web dashboard to create an application, the field *Instance type* is changed to *Resource type* to maintain backward compatibility. [/note] +When using the web dashboard to create an application, the field *Instance type* is changed to *Resource type* to maintain backward compatibility. +``` Similar to other clouds, Anbox Cloud describes the amount of resources that are available to a single instance with an *instance type*. An instance type is a name that is mapped to a set of resources. This allows to have an easy abstraction when referring to resource requirements of instances or particular applications. @@ -46,15 +52,17 @@ g6.3 | 6 | 3 GB | 3 GB | 1 | g8.3 | 8 | 3 GB | 3 GB | 1 | g10.3 | 10 | 3 GB | 3 GB | 1 | +(sec-application-manifest-image)= ## Image -The `image` attribute defines which image the application is based on. If left empty, your application is based on the default image. See [How to manage images](https://discourse.ubuntu.com/t/managing-images/17758) for more details on this. Available images on your installation can be listed with the following command: +The `image` attribute defines which image the application is based on. If left empty, your application is based on the default image. See {ref}`howto-manage-images` for more details on this. Available images on your installation can be listed with the following command: amc image list +(sec-application-manifest-node-selector)= ## Node selector -The `node-selector` attribute allows specifying a list of selectors to limit the LXD nodes on which an instance for the application can be scheduled. AMS will match the selector against the [tags](https://discourse.ubuntu.com/t/how-to-configure-cluster-nodes/28716#tags-5) specified for each node. +The `node-selector` attribute allows specifying a list of selectors to limit the LXD nodes on which an instance for the application can be scheduled. AMS will match the selector against the tags specified for each node. See {ref}`sec-tags` for more information. The following manifest specifies a node selector that instructs the AMS to schedule only those instances having the tags `foo` and `bar`, onto a node: @@ -66,7 +74,7 @@ resources: disk-size: 3GB node-selector: [foo, bar] ``` - +(sec-application-manifest-video-encoder)= ## Video encoder A video encoder type can be specified through the `video-encoder` field in the manifest file when creating an application, so that an instance launched from the application can use a GPU or software video encoder according to different scenarios. Virtual machines do not have GPU support and hence will use software video encoding. @@ -81,6 +89,7 @@ When `gpu` video encoder is specified in the manifest, AMS can fail to create an - All GPU slots are used up by running instances. - There is no GPU support across the entire LXD cluster. +(sec-application-manifest-watchdog)= ## Watchdog The `watchdog` attribute includes the following field definitions: @@ -114,6 +123,7 @@ The rules forbid launching another activity, not part of the installed package o Supplying `['*']` to the `allowed-packages` when the watchdog is enabled allows any application to be displayed in the foreground without triggering a watchdog. +(sec-application-manifest-services)= ## Services An instance launched from the installed application can expose `services` you want to make accessible from outside the instance. You must define the following properties for each service: @@ -125,6 +135,7 @@ Name | Value type | Description `protocols` | array of strings | Protocols to be used by the service (Possible values are: `tcp`, `udp`) `expose` | Boolean | Expose service to be accessible externally or internally +(sec-application-manifest-resources)= ## Resources The `resources` directive helps you define the required resources for your application. @@ -138,8 +149,9 @@ Name | Value type | Minimum value | Description Note that if all required fields (`cpus`/`memory`/`disk-size`) of `resources` are supplied in the application manifest and the deprecated `instance-type` field is also provided, `instance-type` will be overridden by the requirements in the `resources` fields upon application installation. -See [How to configure available resources](https://discourse.ubuntu.com/t/24960) for more information. +See {ref}`exp-resources-presets` for more information. +(sec-application-manifest-extra-data)= ## Extra data Some Android applications which contain large program assets such as graphics or media files use so-called [OBB](https://developer.android.com/google/play/expansion-files) files to store additional data. These data files are separated from the APK and saved onto the external or internal SD card of an Android device. The `extra-data` field can be used in this case to install an APK with separated OBB files or any other additional data into the Android system. @@ -198,10 +210,12 @@ The manifest and extra data in our example are placed next to the application pa └── manifest.yaml ``` +(sec-application-manifest-hooks)= ## Hooks -Hooks allow you to run custom scripts when a certain event is triggered in the life cycle of an instance. See [Hooks](https://discourse.ubuntu.com/t/hooks/28555) for more details about the usage of hooks in an application. +Hooks allow you to run custom scripts when a certain event is triggered in the life cycle of an instance. See {ref}`ref-hooks` for more details about the usage of hooks in an application. +(sec-application-manifest-bootstrap)= ## Bootstrap An application bootstrap can be fine-tuned through the `bootstrap` field. @@ -210,7 +224,7 @@ The `bootstrap` attribute includes the following field definitions: Name | Value type | Description ----------------------|------------|------------------------- -`keep` | array | Contents under the [APP_DIR](https://discourse.ubuntu.com/t/hooks/28555#environment-variables-1) directory to be preserved in the application image after the bootstrap is finished. Wildcard patterns are supported. See [pattern syntax](https://golang.org/pkg/path/filepath/#Match) for more details. +`keep` | array | Contents under the APP_DIR directory to be preserved in the application image after the bootstrap is finished. Wildcard patterns are supported. See {ref}`sec-env-variables` and [pattern syntax](https://golang.org/pkg/path/filepath/#Match) for more information. To minimise the application size, most contents under the `APP_DIR` directory are removed when the application bootstrap is finished. By default, only the metadata content is preserved. If a hook requires any other files under the `APP_DIR` directory during the regular instance runtime, you must include them in the application image. diff --git a/reference/amc-command-reference/addon.md b/reference/cmd-ref/amc-command-reference/addon.md similarity index 90% rename from reference/amc-command-reference/addon.md rename to reference/cmd-ref/amc-command-reference/addon.md index 3603091e..89935cca 100644 --- a/reference/amc-command-reference/addon.md +++ b/reference/cmd-ref/amc-command-reference/addon.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `addon` + The `addon` command allows you to manage addons that are necessary for customising images. amc addon @@ -8,7 +13,7 @@ The following subcommands are available: ### `add` -Create an addon from the contents of the provided directory, tarball or zip archive. See how to [create an addon](https://discourse.ubuntu.com/t/40632) or [create an addon tutorial](https://discourse.ubuntu.com/t/create-an-addon/25284) for more information. +Create an addon from the contents of the provided directory, tarball or zip archive. See {ref}`howto-create-addons` or {ref}`tut-create-addon` for more information. amc addon add ( | | ) --timeout=3m diff --git a/reference/amc-command-reference/application.md b/reference/cmd-ref/amc-command-reference/application.md similarity index 99% rename from reference/amc-command-reference/application.md rename to reference/cmd-ref/amc-command-reference/application.md index 8a0a0597..68909b08 100644 --- a/reference/amc-command-reference/application.md +++ b/reference/cmd-ref/amc-command-reference/application.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `application` + The `application` command allows you to manage applications using the Anbox Management Client (AMC). amc application diff --git a/reference/amc-command-reference/benchmark.md b/reference/cmd-ref/amc-command-reference/benchmark.md similarity index 97% rename from reference/amc-command-reference/benchmark.md rename to reference/cmd-ref/amc-command-reference/benchmark.md index 501f1479..c1424dc8 100644 --- a/reference/amc-command-reference/benchmark.md +++ b/reference/cmd-ref/amc-command-reference/benchmark.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `benchmark` + The `benchmark` command allows you to benchmark your Anbox Cloud deployment. Benchmarking your deployment helps in evaluating the performance of Anbox Cloud for a well-defined workload. amc benchmark ( | ) [options] diff --git a/reference/amc-command-reference/completion.md b/reference/cmd-ref/amc-command-reference/completion.md similarity index 98% rename from reference/amc-command-reference/completion.md rename to reference/cmd-ref/amc-command-reference/completion.md index 3a9cbfcf..05338081 100644 --- a/reference/amc-command-reference/completion.md +++ b/reference/cmd-ref/amc-command-reference/completion.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `completion` + The `completion` command allows you to generate the auto completion script for the specified shell. amc completion diff --git a/reference/amc-command-reference/config.md b/reference/cmd-ref/amc-command-reference/config.md similarity index 90% rename from reference/amc-command-reference/config.md rename to reference/cmd-ref/amc-command-reference/config.md index 1ac0731a..9569b2c8 100644 --- a/reference/amc-command-reference/config.md +++ b/reference/cmd-ref/amc-command-reference/config.md @@ -1,4 +1,9 @@ -The `config` command helps manage the global configuration for the Anbox Management Service (AMS). See [AMS configuration](https://discourse.ubuntu.com/t/20872) for a list of +--- +orphan: true +--- +# `config` + +The `config` command helps manage the global configuration for the Anbox Management Service (AMS). See {ref}`ref-ams-configuration` for a list of available configuration items. amc config diff --git a/reference/amc-command-reference/delete.md b/reference/cmd-ref/amc-command-reference/delete.md similarity index 95% rename from reference/amc-command-reference/delete.md rename to reference/cmd-ref/amc-command-reference/delete.md index ccbc2a5c..3d7ccd1c 100644 --- a/reference/amc-command-reference/delete.md +++ b/reference/cmd-ref/amc-command-reference/delete.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `delete` + The `delete` command deletes an instance. amc delete [options] diff --git a/reference/amc-command-reference/exec.md b/reference/cmd-ref/amc-command-reference/exec.md similarity index 94% rename from reference/amc-command-reference/exec.md rename to reference/cmd-ref/amc-command-reference/exec.md index eb9556d2..7ed67ce3 100644 --- a/reference/amc-command-reference/exec.md +++ b/reference/cmd-ref/amc-command-reference/exec.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `exec` + The `exec` command executes commands directly inside an instance without a shell environment. amc exec -- [options] diff --git a/reference/amc-command-reference/help.md b/reference/cmd-ref/amc-command-reference/help.md similarity index 85% rename from reference/amc-command-reference/help.md rename to reference/cmd-ref/amc-command-reference/help.md index c1da7ff7..c8118aa5 100644 --- a/reference/amc-command-reference/help.md +++ b/reference/cmd-ref/amc-command-reference/help.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `help` + The `help` command displays detailed information about the `amc` tool. amc help diff --git a/reference/amc-command-reference/image.md b/reference/cmd-ref/amc-command-reference/image.md similarity index 96% rename from reference/amc-command-reference/image.md rename to reference/cmd-ref/amc-command-reference/image.md index fc0a919c..e25c666c 100644 --- a/reference/amc-command-reference/image.md +++ b/reference/cmd-ref/amc-command-reference/image.md @@ -1,8 +1,13 @@ +--- +orphan: true +--- +# `image` + The `image` command manages images that contain everything necessary to properly run an Android application in an instance. Images can be provided manually or via an image server. You can add, update or -delete them from AMS. See https://discourse.ubuntu.com/t/24185 and -https://discourse.ubuntu.com/t/17758 for more information. +delete them from AMS. See {ref}`ref-provided-images` and +{ref}`howto-manage-images` for more information. amc image diff --git a/reference/amc-command-reference/info.md b/reference/cmd-ref/amc-command-reference/info.md similarity index 88% rename from reference/amc-command-reference/info.md rename to reference/cmd-ref/amc-command-reference/info.md index aaa4f7b7..d982406f 100644 --- a/reference/amc-command-reference/info.md +++ b/reference/cmd-ref/amc-command-reference/info.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `info` + The `info` command displays general information about the connected AMS service. amc info --format=json diff --git a/reference/amc-command-reference/init.md b/reference/cmd-ref/amc-command-reference/init.md similarity index 98% rename from reference/amc-command-reference/init.md rename to reference/cmd-ref/amc-command-reference/init.md index 3d41679d..c819e588 100644 --- a/reference/amc-command-reference/init.md +++ b/reference/cmd-ref/amc-command-reference/init.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `init` + The `init` command creates an instance but does not start it immediately. amc init [options] diff --git a/reference/cmd-ref/amc-command-reference/landing.md b/reference/cmd-ref/amc-command-reference/landing.md new file mode 100644 index 00000000..0938694b --- /dev/null +++ b/reference/cmd-ref/amc-command-reference/landing.md @@ -0,0 +1,40 @@ +(ref-amc-commands)= +# AMC command reference + +The Anbox Management Client (AMC) is a command line utility offered by Anbox Cloud that interacts with the Anbox Management Service (AMS). + +Use `amc --help` or `amc --help` to display usage information for the tool and its commands. The following commands are available for use with `amc`: + +| Command | Description| +|---------|------------| +|[`addon`](addon.md) | Manage addons | +|[`application`](application.md) | Manage applications | +|[`benchmark`](benchmark.md) | Benchmark your Anbox Cloud deployment | +|[`completion`](completion.md) | Generate the auto completion script for the specified shell | +|[`config`](config.md) | Manage AMS configuration | +|[`delete`](delete.md) | Delete an instance | +|[`exec`](exec.md) | Execute a command inside an instance | +|[`help`](help.md) | Help for a command | +|[`image`](image.md) | Manage images | +|[`info`](info.md) | Provide information about connected AMS service | +|[`init`](init.md) | Initialise an instance | +|[`launch`](launch.md) | Launch an instance | +|[`list`](list.md) | List instances | +|[`logs`](logs.md) | View runtime logs of an instance | +|[`node`](node.md) | Manage nodes | +|[`remote`](remote.md) | Interact with remote AMS daemons | +|[`shell`](shell.md) | Open a shell inside a running instance | +|[`show`](show.md) | Display information about an instance | +|[`show-log`](show-log.md) | Display a particular instance's log file | +|[`start`](start.md) | Start an existing instance | +|[`stop`](stop.md) | Stop a running instance | +|[`wait`](wait.md) | Wait for an instance to reach a specific condition | + +## Options + +You can use the following options or flags with the `amc` utility: + +| Option | Description | +|--------|-------------| +|`-h`, `--help` | Display help for the `amc` utility | +|`-v`, `--version` | Display version of the AMS | diff --git a/reference/amc-command-reference/launch.md b/reference/cmd-ref/amc-command-reference/launch.md similarity index 98% rename from reference/amc-command-reference/launch.md rename to reference/cmd-ref/amc-command-reference/launch.md index 276daf3e..f921df18 100644 --- a/reference/amc-command-reference/launch.md +++ b/reference/cmd-ref/amc-command-reference/launch.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `launch` + The `launch` command launches an instance. amc launch [options] diff --git a/reference/amc-command-reference/list.md b/reference/cmd-ref/amc-command-reference/list.md similarity index 96% rename from reference/amc-command-reference/list.md rename to reference/cmd-ref/amc-command-reference/list.md index 23f94479..17116b2d 100644 --- a/reference/amc-command-reference/list.md +++ b/reference/cmd-ref/amc-command-reference/list.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `list` + The `list` command lists all the instances. amc list [options] diff --git a/reference/amc-command-reference/logs.md b/reference/cmd-ref/amc-command-reference/logs.md similarity index 94% rename from reference/amc-command-reference/logs.md rename to reference/cmd-ref/amc-command-reference/logs.md index e0681302..34e144c7 100644 --- a/reference/amc-command-reference/logs.md +++ b/reference/cmd-ref/amc-command-reference/logs.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `logs` + The `logs` command shows runtime logs of an instance. You can display system-level logs of the instance or the nested Android container. amc logs [options] diff --git a/reference/amc-command-reference/node.md b/reference/cmd-ref/amc-command-reference/node.md similarity index 90% rename from reference/amc-command-reference/node.md rename to reference/cmd-ref/amc-command-reference/node.md index b25181e0..fe1191d3 100644 --- a/reference/amc-command-reference/node.md +++ b/reference/cmd-ref/amc-command-reference/node.md @@ -1,4 +1,9 @@ -The `node` command manage LXD nodes of the deployment that run instances with Anbox Cloud and are managed by the Anbox Management Service (AMS). See https://discourse.ubuntu.com/t/17765 for more information. +--- +orphan: true +--- +# `node` + +The `node` command manage LXD nodes of the deployment that run instances with Anbox Cloud and are managed by the Anbox Management Service (AMS). See {ref}`exp-clustering` for more information. amc node @@ -62,7 +67,9 @@ where `attribute` can be one of the following: Removes a node from the Anbox Cloud cluster thereby making it unable to host instances. -[note type="information" status="Note]You cannot delete a node with running instances unless you use the `--force` flag.[/note] +```{note} +You cannot delete a node with running instances unless you use the `--force` flag. +``` amc node remove [options] @@ -78,7 +85,7 @@ The following options are available: ### `set` -Set specific configuration for a node. See [AMS configuration](https://discourse.ubuntu.com/t/20872) for a list of available configuration items. +Set specific configuration for a node. See {ref}`ref-ams-configuration` for a list of available configuration items. amc node set [options] --timeout=10m diff --git a/reference/amc-command-reference/remote.md b/reference/cmd-ref/amc-command-reference/remote.md similarity index 89% rename from reference/amc-command-reference/remote.md rename to reference/cmd-ref/amc-command-reference/remote.md index eae09e49..de6e13dd 100644 --- a/reference/amc-command-reference/remote.md +++ b/reference/cmd-ref/amc-command-reference/remote.md @@ -1,4 +1,9 @@ -The `remote` command allows interacting with remote Anbox Management Service (AMS) daemons. See [How to control AMS remotely](https://discourse.ubuntu.com/t/17774) for more information. +--- +orphan: true +--- +# `remote` + +The `remote` command allows interacting with remote Anbox Management Service (AMS) daemons. See {ref}`howto-access-ams-remote` for more information. amc remote diff --git a/reference/amc-command-reference/shell.md b/reference/cmd-ref/amc-command-reference/shell.md similarity index 82% rename from reference/amc-command-reference/shell.md rename to reference/cmd-ref/amc-command-reference/shell.md index f597e803..e0161b23 100644 --- a/reference/amc-command-reference/shell.md +++ b/reference/cmd-ref/amc-command-reference/shell.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `shell` + The `shell` command opens a shell inside a running instance. amc shell diff --git a/reference/amc-command-reference/show-log.md b/reference/cmd-ref/amc-command-reference/show-log.md similarity index 85% rename from reference/amc-command-reference/show-log.md rename to reference/cmd-ref/amc-command-reference/show-log.md index 80f50672..371a548a 100644 --- a/reference/amc-command-reference/show-log.md +++ b/reference/cmd-ref/amc-command-reference/show-log.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `show-log` + The `show-log` command shows the log file of an instance. amc show-log diff --git a/reference/amc-command-reference/show.md b/reference/cmd-ref/amc-command-reference/show.md similarity index 86% rename from reference/amc-command-reference/show.md rename to reference/cmd-ref/amc-command-reference/show.md index 8698dded..a3ee6618 100644 --- a/reference/amc-command-reference/show.md +++ b/reference/cmd-ref/amc-command-reference/show.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `show` + The `show` command displays information about an instance. amc show --format=json diff --git a/reference/amc-command-reference/start.md b/reference/cmd-ref/amc-command-reference/start.md similarity index 95% rename from reference/amc-command-reference/start.md rename to reference/cmd-ref/amc-command-reference/start.md index 62ea231c..ba86bd7e 100644 --- a/reference/amc-command-reference/start.md +++ b/reference/cmd-ref/amc-command-reference/start.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `start` + The `start` command starts an existing instance that is in a prepared or a stopped status. This command can be used to start an instance when: * An instance is just initialised with the `amc init` command and not started. * An instance is in an error status. diff --git a/reference/amc-command-reference/stop.md b/reference/cmd-ref/amc-command-reference/stop.md similarity index 93% rename from reference/amc-command-reference/stop.md rename to reference/cmd-ref/amc-command-reference/stop.md index 7199b889..aa2eb8fd 100644 --- a/reference/amc-command-reference/stop.md +++ b/reference/cmd-ref/amc-command-reference/stop.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `stop` + The `stop` command stops a running instance. amc stop [options] diff --git a/reference/amc-command-reference/wait.md b/reference/cmd-ref/amc-command-reference/wait.md similarity index 96% rename from reference/amc-command-reference/wait.md rename to reference/cmd-ref/amc-command-reference/wait.md index 0612ebce..d0d82d32 100644 --- a/reference/amc-command-reference/wait.md +++ b/reference/cmd-ref/amc-command-reference/wait.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `wait` + The `wait` command waits for an instance to reach a specific condition. amc wait ( | ) --condition [options] diff --git a/reference/appliance-command-reference/ams.md b/reference/cmd-ref/appliance-command-reference/ams.md similarity index 95% rename from reference/appliance-command-reference/ams.md rename to reference/cmd-ref/appliance-command-reference/ams.md index 81e63a2b..4fb53d26 100644 --- a/reference/appliance-command-reference/ams.md +++ b/reference/cmd-ref/appliance-command-reference/ams.md @@ -1,3 +1,8 @@ +--- +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 diff --git a/reference/appliance-command-reference/dashboard.md b/reference/cmd-ref/appliance-command-reference/dashboard.md similarity index 74% rename from reference/appliance-command-reference/dashboard.md rename to reference/cmd-ref/appliance-command-reference/dashboard.md index 15b757c8..c0c7714e 100644 --- a/reference/appliance-command-reference/dashboard.md +++ b/reference/cmd-ref/appliance-command-reference/dashboard.md @@ -1,4 +1,9 @@ -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 [Register an Ubuntu One account in Anbox Cloud Appliance](https://discourse.ubuntu.com/t/web-dashboard/20871#register-an-ubuntu-one-account-in-anbox-cloud-appliance-3) for more information. +--- +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. anbox-cloud-appliance dashboard diff --git a/reference/appliance-command-reference/destroy.md b/reference/cmd-ref/appliance-command-reference/destroy.md similarity index 57% rename from reference/appliance-command-reference/destroy.md rename to reference/cmd-ref/appliance-command-reference/destroy.md index d5f19f9e..6172a61a 100644 --- a/reference/appliance-command-reference/destroy.md +++ b/reference/cmd-ref/appliance-command-reference/destroy.md @@ -1,8 +1,15 @@ +--- +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 -[note type="caution" status="Warning"]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.[/note] +```{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 diff --git a/reference/appliance-command-reference/gateway.md b/reference/cmd-ref/appliance-command-reference/gateway.md similarity index 90% rename from reference/appliance-command-reference/gateway.md rename to reference/cmd-ref/appliance-command-reference/gateway.md index 56fd05e7..e1d4f02f 100644 --- a/reference/appliance-command-reference/gateway.md +++ b/reference/cmd-ref/appliance-command-reference/gateway.md @@ -1,3 +1,8 @@ +--- +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 @@ -16,7 +21,7 @@ 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 [How to access the stream gateway](https://discourse.ubuntu.com/t/managing-stream-gateway-access/17784) for more information. +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 diff --git a/reference/appliance-command-reference/help.md b/reference/cmd-ref/appliance-command-reference/help.md similarity index 87% rename from reference/appliance-command-reference/help.md rename to reference/cmd-ref/appliance-command-reference/help.md index 91db31eb..0c950796 100644 --- a/reference/appliance-command-reference/help.md +++ b/reference/cmd-ref/appliance-command-reference/help.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `help` + The `help` command displays detailed information about the `anbox-cloud-appliance` tool. anbox-cloud-appliance help diff --git a/reference/appliance-command-reference/init.md b/reference/cmd-ref/appliance-command-reference/init.md similarity index 89% rename from reference/appliance-command-reference/init.md rename to reference/cmd-ref/appliance-command-reference/init.md index 74a127f5..7d0e2758 100644 --- a/reference/appliance-command-reference/init.md +++ b/reference/cmd-ref/appliance-command-reference/init.md @@ -1,8 +1,13 @@ +--- +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. anbox-cloud-appliance init -See [Initialise the appliance](https://discourse.ubuntu.com/t/install-the-anbox-cloud-appliance-on-a-dedicated-machine/22681#initialise-the-appliance-6) for more information. +See {ref}`sec-initialise-appliance` for more information. ## Options diff --git a/reference/cmd-ref/appliance-command-reference/landing.md b/reference/cmd-ref/appliance-command-reference/landing.md new file mode 100644 index 00000000..5b522e51 --- /dev/null +++ b/reference/cmd-ref/appliance-command-reference/landing.md @@ -0,0 +1,21 @@ +(ref-appliance-commands)= +# Appliance command reference + +The `anbox-cloud-appliance` is a command line client to manage the appliance and its components. + +Use `anbox-cloud-appliance --help` or `anbox-cloud-appliance --help` to display usage information for the tool and its commands. + +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| +|[`status`](status.md) | Display the current status and version of the appliance| +|[`upgrade`](upgrade.md) | Upgrade the appliance to a newer version| + +If you encounter an issue and want to collect debugging information from the appliance, use `anbox-cloud-appliance.buginfo`. diff --git a/reference/appliance-command-reference/status.md b/reference/cmd-ref/appliance-command-reference/status.md similarity index 92% rename from reference/appliance-command-reference/status.md rename to reference/cmd-ref/appliance-command-reference/status.md index c16a6dc3..e6721565 100644 --- a/reference/appliance-command-reference/status.md +++ b/reference/cmd-ref/appliance-command-reference/status.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# `status` + The `status` command displays the following information about the Anbox Cloud Appliance: * Status of the appliance diff --git a/reference/appliance-command-reference/upgrade.md b/reference/cmd-ref/appliance-command-reference/upgrade.md similarity index 74% rename from reference/appliance-command-reference/upgrade.md rename to reference/cmd-ref/appliance-command-reference/upgrade.md index 8025a30d..977b4562 100644 --- a/reference/appliance-command-reference/upgrade.md +++ b/reference/cmd-ref/appliance-command-reference/upgrade.md @@ -1,6 +1,11 @@ +--- +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 [How to upgrade the appliance](https://discourse.ubuntu.com/t/upgrade-anbox-cloud-appliance/24186) for more information. +See {ref}`howto-upgrade-appliance` for more information. ## Usage diff --git a/reference/cmd-ref/landing.md b/reference/cmd-ref/landing.md new file mode 100644 index 00000000..d2cd40f0 --- /dev/null +++ b/reference/cmd-ref/landing.md @@ -0,0 +1,9 @@ +# Command reference + +This section provides command reference for the following command line utilities: + +```{toctree} +:titlesonly: +amc-command-reference/landing.md +appliance-command-reference/landing.md +``` \ No newline at end of file diff --git a/reference/component-versions.md b/reference/component-versions.md index 31b8d13d..56587fbd 100644 --- a/reference/component-versions.md +++ b/reference/component-versions.md @@ -1,6 +1,9 @@ +(ref-component-versions)= +# Component versions + This documents the versions of the different components for each Anbox Cloud release. -Not all components are updated with each release. When components are not updated, this is called out in the [release notes](https://discourse.ubuntu.com/t/release-notes/17842) and components are marked with `n/a` below. +Not all components are updated with each release. When components are not updated, they are marked with `n/a` below. ## 1.22.1 @@ -193,9 +196,7 @@ N/A ## 1.21.0 -### Charms - -#### Ubuntu 22.04 +### Charms for Ubuntu 22.04 | Name | Channel | Revision | |----------|--------------|--------------| @@ -209,7 +210,7 @@ N/A | `anbox-stream-agent` | `1.21/stable` | 320 | | `nats ` | `latest/stable` | 11 | -#### Ubuntu 20.04 +### Charms for Ubuntu 20.04 | Name | Channel | Revision | |----------|--------------|--------------| diff --git a/reference/deprecation-notices.md b/reference/deprecation-notices.md index 4628d457..98f0622e 100644 --- a/reference/deprecation-notices.md +++ b/reference/deprecation-notices.md @@ -1,3 +1,5 @@ +# Deprecation notices + This document contains a list of deprecation notices for Anbox Cloud and its components. ## Ubuntu 20.04 (focal) diff --git a/reference/glossary.md b/reference/glossary.md index 64023651..7bc56983 100644 --- a/reference/glossary.md +++ b/reference/glossary.md @@ -1,264 +1,159 @@ -[Details="Alphabetical list of terms"] -- [AAM](#aam) -- [AAR (Anbox Application Registry)](#aar) -- [AAR (Android Archive)](#android-archive) -- [ADB](#adb) -- [AMC](#amc) -- [AMS](#ams) -- [AMS Node Controller](#ams-node-controller) -- [AMS SDK](#ams-sdk) -- [APK](#apk) -- [AWS](#aws) -- [Addon](#addon) -- [Amazon Web Services](#aws) -- [Anbox](#anbox) -- [Anbox Application Manager](#aam) -- [Anbox Application Registry](#aar) -- [Anbox Cloud](#anbox-cloud) -- [Anbox Cloud Appliance](#anbox-cloud-appliance) -- [Anbox Cloud cluster](#anbox-cloud-cluster) -- [Anbox Cloud subcluster](#anbox-cloud-subcluster) -- [Anbox Management Client](#amc) -- [Anbox Management Service](#ams) -- [Anbox Platform SDK](#anbox-platform-sdk) -- [Anbox shell](#anbox-shell) -- [Anbox Streaming SDK](#anbox-streaming-sdk) -- [Android app](#android-app) -- [Android Archive](#android-archive) -- [Android Debug Bridge](#adb) -- [Android Package Kit](#apk) -- [Appium](#appium) -- [Application](#application) -- [Application instance](#application-instance) -- [Application manifest](#application-manifest) -- [Base instance](#base-instance) -- [Boot package](#boot-package) -- [Bootstrap process](#bootstrap-process) -- [Control node](#control-node) -- [Core stack](#core-stack) -- [Coturn](#coturn) -- [GPU](#gpu) -- [Graphics Processing Unit](#gpu) -- [HA](#ha) -- [High availability](#ha) -- [Hook](#hook) -- [Image](#image) -- [Instance](#instance) -- [Instance type](#instance-type) -- [Juju](#juju) -- [LXD](#lxd) -- [LXD cluster](#lxd-cluster) -- [LXD worker node](#lxd-worker-node) -- [Manifest](#application-manifest) -- [NATS](#nats) -- [Neural Autonomic Transport System](#nats) -- [Node controller](#ams-node-controller) -- [NRPE](#nrpe) -- [Platform](#platform) -- [Prometheus](#prometheus) -- [Raw instance](#raw-instance) -- [Regular instance](#regular-instance) -- [STUN/TURN server](#stun/turn-server) -- [Scrcpy](#scrcpy) -- [Session](#session) -- [Snap](#snap) -- [Software Rasterization](#swrast) -- [Stream agent](#stream-agent) -- [Stream gateway](#stream-gateway) -- [Streaming stack](#streaming-stack) -- [`swrast`](#swrast) -- [Ubuntu Pro](#ubuntu-pro) -- [Ubuntu One](#ubuntu-one) -- [Watchdog](#watchdog) -- [Web dashboard](#web-dashboard) -- [WebRTC](#webrtc) - -[/Details] - -## Definitions - - -### Addon +(ref-glossary)= +# Glossary + +## Addon A piece of code that can be used to extend and customise images in Anbox Cloud. -See https://discourse.ubuntu.com/t/addons/25293. +See {ref}`ref-addon-manifest` for more information. - -### Amazon Web Services (AWS) +## Amazon Web Services (AWS) A cloud platform provided by Amazon that can be used to host Anbox Cloud. -See [the AWS website](https://aws.amazon.com/). +See [the AWS website](https://aws.amazon.com/) for more information. - -### AMS Node Controller +## AMS Node Controller A service that runs on every LXD node and puts the appropriate firewall rules in place when an instance is started or stopped. - -### AMS SDK +## AMS SDK An SDK that provides Go language bindings for connecting to AMS through the exposed REST API. -See [AMS SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#ams-sdk-4). +See {ref}`sec-ams-sdk` for more information. - -### Anbox +## Anbox A component of Anbox Cloud that facilitates booting an Android system on a regular GNU/Linux system. The concepts of the Anbox component in Anbox Cloud are similar to the [Anbox open source project](https://github.com/anbox/anbox), but the Anbox open source project is an independent project that is not related to or used in Anbox Cloud. - -### Anbox Application Manager (AAM) +## Anbox Application Manager (AAM) A utility (`aam`) that is installed in the Anbox image and that can be used for various tasks, for example, to back up and restore Android application data. -See https://discourse.ubuntu.com/t/back-up-and-restore-application-data/24183. +See {ref}`howto-backup-restore-application-data` for more information. - -### Anbox Application Registry (AAR) +## Anbox Application Registry (AAR) A central repository for applications created in Anbox Cloud. Using an AAR is very useful for larger deployments to keep applications in sync. -See https://discourse.ubuntu.com/t/anbox-application-registry-aar/17761. +See {ref}`exp-aar` for more information. - -### Anbox Cloud +## Anbox Cloud A rich software stack that enables you to run Android applications in the cloud for all kinds of different use cases, including high-performance streaming of graphics to desktop and mobile client devices. -See https://discourse.ubuntu.com/t/about-anbox-cloud/17802. +See {ref}`exp-anbox-cloud` for more information. - -### Anbox Cloud Appliance +## Anbox Cloud Appliance A self-contained deployment variant of Anbox Cloud. -See [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1). +See {ref}`sec-variants` for more information. - -### Anbox Cloud cluster +## Anbox Cloud cluster A deployment of the Anbox Cloud, either just the core stack or the core stack along with the streaming stack. - -### Anbox Cloud subcluster +## Anbox Cloud subcluster The group of components that is made up of LXD, AMS node controller, and the [control node](#control-node) hosting the AMS, AMC, and etcd. - -### Anbox Management Client (AMC) +## Anbox Management Client (AMC) The command line interface that is used to manage the Anbox Management Service (AMS). - -### Anbox Management Service (AMS) +## Anbox Management Service (AMS) The service that handles all aspects of the application and instance life cycle in Anbox Cloud. AMS is responsible for managing instances, applications, addons, updates and more, ensuring high density, performance and fast startup times for the instances. AMS uses [etcd](https://etcd.io/) as database. It connects to LXD over its REST API. -See https://discourse.ubuntu.com/t/anbox-management-service-ams/24321. +See {ref}`exp-ams` for more information. - -### Anbox Platform SDK +## Anbox Platform SDK A C/C++ SDK that provides support for developing custom platform plugins, which allows users to integrate Anbox with their existing infrastructure. -See [Anbox Platform SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-platform-sdk). +See {ref}`sec-platform-sdk` for more information. - -### Anbox shell +## Anbox shell A command-line tool (`anbox-shell`) that provides an ADB shell with root permissions granted, which you can use to access the Android system in the instance. -See [Access an instance with AMC](https://discourse.ubuntu.com/t/17772#access-an-instance-with-amc-1). +See {ref}`howto-access-instance` for more information. - -### Anbox Streaming SDK +## Anbox Streaming SDK An SDK that allows the development of custom streaming clients, using JavaScript. -See [Anbox Streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8). +See {ref}`sec-streaming-sdk` for more information. - -### Android app +## Android app An application for the Android mobile operating system, usually provided as APK. To distinguish Android apps from Anbox Cloud applications, this documentation refers to Android apps as "apps", not "applications". - -### Android Archive (AAR) +## Android Archive (AAR) A compiled version of an Android library that can be used as a dependency for an Android app module. See [Create an Android library](https://developer.android.com/studio/projects/android-library) in the Android developer documentation. - -### Android Debug Bridge (ADB) +## Android Debug Bridge (ADB) A command-line tool that is included in the Android SDK Platform-Tools package and that allows to connect to and communicate with an Android device from your computer. See [Android Debug Bridge (ADB)](https://developer.android.com/studio/command-line/adb) in the Android developer documentation. - -### Android Package Kit (APK) +## Android Package Kit (APK) The file format used to package apps for the Android operating system. - -### Appium +## Appium An open-source test automation tool that can be used to test native, mobile and hybrid web applications on Android. -See [the Appium website](http://appium.io/). +See [the Appium website](http://appium.io/) for more information. - -### Application +## Application One of the main objects of Anbox Cloud. An application encapsulates an Android app and manages it within the Anbox Cloud cluster. -See https://discourse.ubuntu.com/t/about-applications/17760. +See {ref}`exp-applications` for more information. - -### Application instance +## Application instance An instance that is created when launching an application. -See [Application instances vs. raw instances](https://discourse.ubuntu.com/t/17763#application-vs-raw). +See {ref}`sec-application-raw-instances` for more information. - -### Application manifest +## Application manifest A file that defines the attributes of an Anbox Cloud application. -See https://discourse.ubuntu.com/t/application-manifest/24197. +See {ref}`ref-application-manifest` for more information. - -### Base instance +## Base instance A temporary instance that is used when bootstrapping an application. It is automatically deleted when the application bootstrap is completed. -See https://discourse.ubuntu.com/t/17763#regular-vs-base. +See {ref}`sec-regular-base-instances` for more information. - -### Boot package +## Boot package The package to launch in an application instance once the system has booted. - -### Bootstrap process +## Bootstrap process The process that builds the application and optimises it to run on Anbox Cloud. -See [Bootstrap process](https://discourse.ubuntu.com/t/about-applications/17760#bootstrap-process-2). +See {ref}`sec-application-bootstrap` for more information. - -### Control node +## Control node The machine on which the components that make up the management layer, AMS, AMC, and etcd, are installed. - -### Core stack +## Core stack The core parts of the Anbox Cloud stack that are required for all deployments. As a bare minimum, an Anbox Cloud deployment requires the following services: @@ -268,203 +163,175 @@ The core parts of the Anbox Cloud stack that are required for all deployments. A - 1 AMS Node Controller per LXD worker - Easy-RSA -See https://discourse.ubuntu.com/t/about-anbox-cloud/17802. +See {ref}`exp-anbox-cloud` for more information. - -### Coturn +## Coturn An open-source implementation of a STUN/TURN server needed for WebRTC to work behind NATs and firewalls. -See [the Coturn project on GitHub](https://github.com/coturn/coturn). +See [the Coturn project on GitHub](https://github.com/coturn/coturn) for more information. - -### Graphics Processing Unit (GPU) +## Graphics Processing Unit (GPU) A specialised processor that is designed to accelerate image processing and graphics rendering for output to a display device. - -### High availability (HA) +## High availability (HA) The characteristic of a system to continuously be available without failing for a higher-than-normal period of time. Anbox Cloud ensures high availability by keeping replicas of every service, which avoids having a single point of failure. -See [Enable high availability](https://discourse.ubuntu.com/t/enable-high-availability/17754). +See {ref}`howto-enable-ha` for more information. - -### Hook +## Hook Code that is invoked at different points in time in the life cycle of an instance. Hooks are part of addons or applications. -See [Hooks](https://discourse.ubuntu.com/t/hooks/28555). +See {ref}`ref-hooks` for more information. - -### Image +## Image The base for an instance, which contains all necessary components like Anbox or the Android root file system. Anbox Cloud provides images based on different Android and Ubuntu versions and different architectures. The images can be an Anbox Cloud AOSP image which is based on the Android Open Source Project (AOSP), an operating system typically used in mobile devices or an Anbox Cloud AAOS image which is based on the Android Automotive OS (AAOS), an infotainment platform used in automobiles. -See [Manage images](https://discourse.ubuntu.com/t/manage-images/17758) and [Provided images](https://discourse.ubuntu.com/t/provided-images/24185). +See {ref}`howto-manage-images` and {ref}`ref-provided-images` for more information. - -### Instance +## Instance An instance is a container or a virtual machine used to launch an application or an image. Every time you launch an application or an image, Anbox Cloud creates an instance for it. Every instance provides a full Android system. -See https://discourse.ubuntu.com/t/17763. +See {ref}`exp-instances` for more information. - -### Instance type +## Instance type An abstraction for a set of resources that is available to an instance. -See https://discourse.ubuntu.com/t/application-manifest/24197#instance-type-1. +See {ref}`sec-application-manifest-instance-type` for more information. -[note type="information" status="Note"] The `instance-type` attribute in the application manifest will be deprecated effective version 1.20 and will be removed in future releases. After the `instance-type` attribute becomes unsupported, this term will be replaced with the term *Resource preset*.[/note] +```{note} +The `instance-type` attribute in the application manifest will be deprecated effective version 1.20 and will be removed in future releases. After the `instance-type` attribute becomes unsupported, this term will be replaced with the term *Resource preset*. +``` - -### Juju +## Juju A charmed operator framework that helps you deploy, integrate and manage applications across multiple environments. Anbox Cloud is installed using Juju. The Anbox Cloud Appliance uses Juju under the hood. -See [the Juju website](https://juju.is/). +See [the Juju website](https://juju.is/) for more information. - -### LXD +## LXD A system container and virtual machine manager that offers a unified user experience around full Linux systems running inside containers or virtual machines. Anbox Cloud is based on LXD. -See [the LXD website](https://ubuntu.com/lxd). - - -### LXD cluster +See [the LXD website](https://ubuntu.com/lxd) for more information. +## LXD cluster A set of LXD nodes that share the same distributed database that holds the configuration for the cluster members and their instances. - -### LXD worker node +## LXD worker node -In a clustering setup for a full Anbox Cloud deployment, all nodes other than the [control node](#control-node) are worker nodes. If you have a streaming stack, all nodes other than the [control node](#control-node) and the two nodes that are dedicated to host the streaming services are worker nodes. Each worker node runs LXD in clustering mode, and this LXD cluster is used to host the Android containers. +In a clustering setup for a full Anbox Cloud deployment, all nodes other than the [control node](#control-node) are worker nodes. If you have a streaming stack, all nodes other than the control node and the two nodes that are dedicated to host the streaming services are worker nodes. Each worker node runs LXD in clustering mode, and this LXD cluster is used to host the Android containers. - -### Neural Autonomic Transport System (NATS) +## Neural Autonomic Transport System (NATS) An open-source messaging system that the components of the streaming stack use to communicate. -See [the NATS website](https://nats.io/). +See [the NATS website](https://nats.io/) for more information. - -### Platform +## Platform An abstraction layer that is provided by Anbox to access the hardware resources of the host system from the Android system. Anbox Cloud supports three platforms: `null` (without rendering), `webrtc` (WebRTC) and `swrast` (software rendering). -See https://discourse.ubuntu.com/t/anbox-platforms/18733. +See {ref}`exp-platforms` for more information. - -### Prometheus +## Prometheus An open-source application used for event monitoring and alerting, which records real-time metrics about system events. -See [the Prometheus website](https://prometheus.io/). +See [the Prometheus website](https://prometheus.io/) for more information. - -### Raw instance +## Raw instance An instance that is created when launching an image. It runs the full Android system, without any additional apps installed. -See [Application instances vs. raw instances](https://discourse.ubuntu.com/t/17763#application-vs-raw). +See {ref}`sec-application-raw-instances` for more information. - -### Regular instance +## Regular instance An instance that is launched from either an application or an image. It exists until it is deleted. -See [Regular instances vs. base instances](https://discourse.ubuntu.com/t/17763#regular-vs-base). +See {ref}`sec-regular-base-instances` for more information. - -### Scrcpy +## Scrcpy An open-source screen mirroring application that allows displaying and controlling Android devices from a desktop computer. -See [the scrcpy project on GitHub](https://github.com/Genymobile/scrcpy). +See [the scrcpy project on GitHub](https://github.com/Genymobile/scrcpy) for more information. - -### Session +## Session The interaction between a streaming client and the application instance during streaming. A session contains, among other information, user data and application information and provides an entry point for both the client and the instance to start the signalling process. -See https://discourse.ubuntu.com/t/about-application-streaming/17769. +See {ref}`exp-application-streaming` for more information. - -### Snap +## Snap A software package for a desktop, cloud or IoT application that is easy to install, secure, cross‐platform and dependency‐free. -See [the Snapcraft website](https://snapcraft.io/). +See [the Snapcraft website](https://snapcraft.io/) for more information. - -### Software Rasterization (`swrast`) +## Software Rasterization (`swrast`) An LLVMpipe-based software rendering platform that is useful for visual tests but does not provide audio input/output. -See https://discourse.ubuntu.com/t/anbox-platforms/18733. +See {ref}`exp-platforms` for more information. - -### Stream agent +## Stream agent The software running on a server connected to Anbox Cloud, which connects AMS to the stream gateway and allows distribution from the gateway to multiple independent AMS installations. -See https://discourse.ubuntu.com/t/about-application-streaming/17769. +See {ref}`exp-application-streaming` for more information. - -### Stream gateway +## Stream gateway The central component that connects clients with stream agents. Its role is to choose the best possible region depending on the user location and server capacities. -See https://discourse.ubuntu.com/t/about-application-streaming/17769. +See {ref}`exp-application-streaming` for more information. - -### Streaming stack +## Streaming stack A collection of components designed to run containers or virtual machines and stream their visual output to clients via WebRTC. Streaming can happen through GPUs or through software rendering. -See https://discourse.ubuntu.com/t/about-application-streaming/17769. +See {ref}`exp-application-streaming` for more information. - -### STUN/TURN server +## STUN/TURN server A server that finds the most optimal network path between a client and the instance running its application. - -### Ubuntu Pro +## Ubuntu Pro Canonical’s service package for Ubuntu that provides enterprise security and support for open-source applications, with managed service offerings available. Note the difference between Ubuntu Pro (Infra-only) and Ubuntu Pro subscriptions. Anbox Cloud requires an Ubuntu Pro subscription. -See [Ubuntu Pro](https://ubuntu.com/support). +See [Ubuntu Pro](https://ubuntu.com/support) for more information. - -### Ubuntu One +## Ubuntu One A central user account system used by all Canonical sites and services. You need an Ubuntu One account to purchase the Ubuntu Pro subscription that is required to run Anbox Cloud, and to log in to the web dashboard. -See [Ubuntu One](https://login.ubuntu.com/). +See [Ubuntu One](https://login.ubuntu.com/) for more information. - -### Watchdog +## Watchdog A software component that monitors the app in an instance and terminates the instance if the app crashes or is moved to the background. -See [Watchdog settings](https://discourse.ubuntu.com/t/application-manifest/24197#watchdog-5). +See {ref}`sec-application-manifest-watchdog` for more information. - -### Web dashboard +## Web dashboard A web GUI for Anbox Cloud from where developers can create, manage and stream applications from their web browser. -See https://discourse.ubuntu.com/t/use-the-web-dashboard/20871. +See {ref}`exp-web-dashboard` for more information. - -### WebRTC +## WebRTC A standard for media capture devices and peer-to-peer connectivity that can be used to add real-time communication capabilities to an application. It supports video, voice, and generic data to be sent between peers. -See [the WebRTC website](https://webrtc.org/). +See [the WebRTC website](https://webrtc.org/) for more information. diff --git a/reference/hooks.md b/reference/hooks.md index ba62871c..e8b1e86d 100644 --- a/reference/hooks.md +++ b/reference/hooks.md @@ -1,4 +1,7 @@ -Hooks are scripts that automatically trigger actions based on an event performed in the life cycle of an [instance](https://discourse.ubuntu.com/t/26204#instance). A hook can be any executable file that is placed in the `hooks` directory of an addon or an application folder. +(ref-hooks)= +# Hooks + +Hooks are scripts that automatically trigger actions based on an event performed in the life cycle of an instance. A hook can be any executable file that is placed in the `hooks` directory of an addon or an application folder. The hook name **must** be one of the following: @@ -12,12 +15,13 @@ The hook name **must** be one of the following: | restore (deprecated) | DEPRECATED: Use `pre-start` instead. Executed before Android starts. | | backup (deprecated) | DEPRECATED: Use `post-stop` instead. Executed after Android shuts down. | -A failed hook will cause the instance to stop immediately and end up in an error state. In such cases, [view the instance logs](https://discourse.ubuntu.com/t/24329) to further investigate the causes of failure. +A failed hook will cause the instance to stop immediately and end up in an error state. In such cases, see {ref}`howto-view-instance-logs` to further investigate the causes of failure. The following figure shows when the different hooks are executed in the life cycle of a base or a regular instance. ![Hooks execution in the life cycle of an instance |471x601](https://assets.ubuntu.com/v1/8441e690-addons-reference-hook-order.png) +(sec-env-variables)= ## Environment variables When hooks are invoked, several environment variables are set to provide context to the addon. diff --git a/reference/landing.md b/reference/landing.md index 4875ee3c..816be4b4 100644 --- a/reference/landing.md +++ b/reference/landing.md @@ -1,3 +1,6 @@ +(reference)= +# Reference + The reference guides in this section provide additional information about using Anbox Cloud, release information, available configuration options, performance metrics and benchmarks. ## Releases and versions @@ -6,10 +9,10 @@ Learn about Anbox Cloud releases, release roadmap, supported product versions an | Guides | Description | |--|--| -| [Release roadmap](https://discourse.ubuntu.com/t/19359) | Information about general release cycle, currently supported version and future releases | -| [Release notes](https://discourse.ubuntu.com/t/17842) | Release notes for all versions of Anbox Cloud | -| [Component versions](https://discourse.ubuntu.com/t/21413) | Version information about different components of Anbox Cloud for each release | -| [Supported versions](https://discourse.ubuntu.com/t/supported-versions/21046) | Information about supported Anbox Cloud versions and professional support | +| {ref}`ref-roadmap` | Information about general release cycle, currently supported version and future releases | +| {ref}`ref-release-notes` | Release notes for all versions of Anbox Cloud | +| {ref}`ref-component-versions` | Version information about different components of Anbox Cloud for each release | +| {ref}`ref-supported-versions` | Information about supported Anbox Cloud versions and professional support | ## Usage @@ -17,16 +20,16 @@ Understand the difference aspects of using Anbox Cloud such as requirements, sup | Guides | Description | |--|--| -| [Requirements](https://discourse.ubuntu.com/t/17734)| Hardware and software requirements to use Anbox Cloud | -| [Provided images](https://discourse.ubuntu.com/t/24185)| A list of official images that Anbox Cloud provides | -| [Supported rendering resources](https://discourse.ubuntu.com/t/37322)| A list of supported GPU vendors, drivers, platforms, APIs etc. | -| [Supported video codecs](https://discourse.ubuntu.com/t/37323)| A list of supported video codecs | -| [Supported Android features](https://discourse.ubuntu.com/t/28825)| Overview of Android features and which of them are supported by Anbox Cloud | -| [API reference](https://discourse.ubuntu.com/t/24339)| APIs that Anbox Cloud provides | -| [Anbox Cloud SDKs](https://discourse.ubuntu.com/t/17844)| Overview of the SDKs that Anbox Cloud provides to facilitate integrating and extending the solution | -| [Network ports](https://discourse.ubuntu.com/t/33650)| A list of network ports that Anbox Cloud exposes for each service | -| [Addons](https://discourse.ubuntu.com/t/25293)| Documentation of the addon mechanism | -| [Hooks](https://discourse.ubuntu.com/t/28555)| Documentation of hooks for addons or applications | +| {ref}`ref-requirements`| Hardware and software requirements to use Anbox Cloud | +| {ref}`ref-provided-images`| A list of official images that Anbox Cloud provides | +| {ref}`ref-rendering-resources`| A list of supported GPU vendors, drivers, platforms, APIs etc. | +| {ref}`ref-codecs`| A list of supported video codecs | +| {ref}`ref-android-features`| Overview of Android features and which of them are supported by Anbox Cloud | +| {ref}`ref-api`| APIs that Anbox Cloud provides | +| {ref}`ref-sdks`| Overview of the SDKs that Anbox Cloud provides to facilitate integrating and extending the solution | +| {ref}`ref-network-ports`| A list of network ports that Anbox Cloud exposes for each service | +| {ref}`ref-addon-manifest`| List of keys in the addon manifest | +| {ref}`ref-hooks`| Information about hooks for addons or applications and related environment variables | ## Configuration @@ -34,23 +37,61 @@ Know the configuration options that can be defined for various components of Anb | Guides | Description | |--|--| -| [AMS configuration](https://discourse.ubuntu.com/t/20872)| Configuration options for Anbox Management Service (AMS) | -| [Application manifest](https://discourse.ubuntu.com/t/24197)| A list of attributes that can be specified in the application manifest | -| [WebRTC streamer](https://discourse.ubuntu.com/t/30195)| Configuration details for the WebRTC streamer | +| {ref}`ref-ams-configuration`| Configuration options for Anbox Management Service (AMS) | +| {ref}`ref-application-manifest`| A list of attributes that can be specified in the application manifest | +| {ref}`ref-webrtc`| Configuration details for the WebRTC streamer | + +## Command reference + +Learn about the commands and their usage for the Anbox Management Client (AMC) and the Anbox Cloud Appliance. + +| Guides | Description | +|--|--| +| {ref}`ref-amc-commands`| Commands and their usage when using the AMC | +| {ref}`ref-appliance-commands`| Commands and their usage when using the appliance | ## Performance Learn about the available metrics and benchmarks for measuring performance. | Guides | Description | |--|--| -| [Prometheus metrics](https://discourse.ubuntu.com/t/19521)| Performance metrics that Anbox Cloud provides | -| [Performance benchmarks](https://discourse.ubuntu.com/t/24709)| Benchmarks for the performance that you can achieve with different versions and configurations of Anbox Cloud | +| {ref}`ref-prometheus-metrics`| Performance metrics that Anbox Cloud provides | +| {ref}`ref-performance-benchmarks`| Benchmarks for the performance that you can achieve with different versions and configurations of Anbox Cloud | -## Other related information +## Other | Guides | Description | |--|--| -| [License information](https://discourse.ubuntu.com/t/36649)| Information on where to find the licenses of components used by Anbox Cloud | -| [Glossary](https://discourse.ubuntu.com/t/glossary/26204)| Useful terminology for working with Anbox Cloud | +| {ref}`ref-license-information`| Information on where to find the licenses of components used by Anbox Cloud | +| {ref}`ref-glossary`| Useful terminology for working with Anbox Cloud | + +Also check out the {ref}`tutorials` for step-by-step instructions that help you get familiar with Anbox Cloud, the {ref}`how-to-guides` for instructions on how to achieve specific goals when using Anbox Cloud and the {ref}`explanation` section for background information. + +```{toctree} +:hidden: -Also check out the [Tutorials](https://discourse.ubuntu.com/t/tutorials/28826) for step-by-step instructions that help you get familiar with Anbox Cloud, the [How-to guides](https://discourse.ubuntu.com/t/how-to-guides/28827) for instructions on how to achieve specific goals when using Anbox Cloud and the [Explanation](https://discourse.ubuntu.com/t/explanation/28829) section for background information. +addon-manifest +ams-configuration +sdks +api-reference +application-manifest +cmd-ref/landing.md +component-versions +deprecation-notices +glossary +hooks +license-information +network-ports +perf-benchmarks +prometheus +provided-images +release-notes/release-notes.md +requirements +roadmap +android-features +anbox-features +supported-rendering-resources +supported-versions +supported-codecs +webrtc-streamer +``` \ No newline at end of file diff --git a/reference/license-information.md b/reference/license-information.md index 35e40253..30e46aea 100644 --- a/reference/license-information.md +++ b/reference/license-information.md @@ -1,3 +1,5 @@ +(ref-license-information)= +# License information The copyright and license information of Anbox Cloud can be found within the container or the virtual machine at `/usr/share/doc/anbox/copyright`. Anbox Cloud is built using multiple open source software components. This guide lists those components and where to find their license information. diff --git a/reference/network-ports.md b/reference/network-ports.md index 7256da51..36859ef5 100644 --- a/reference/network-ports.md +++ b/reference/network-ports.md @@ -1,3 +1,6 @@ +(ref-network-ports)= +# Network ports + Anbox Cloud exposes certain network ports for access and communication. For the regular Anbox Cloud deployment, these ports are used for communication between components, and to allow accessing the Anbox Cloud interface. diff --git a/reference/perf-benchmarks.md b/reference/perf-benchmarks.md index 9f5e15d8..96c6bfb9 100644 --- a/reference/perf-benchmarks.md +++ b/reference/perf-benchmarks.md @@ -1,6 +1,9 @@ +(ref-performance-benchmarks)= +# Performance benchmarks + The following benchmarks give an overview of the performance that you can achieve with Anbox Cloud. -The benchmarks were performed using the `amc benchmark` utility as described in [How to run benchmarks](https://discourse.ubuntu.com/t/benchmarking-a-deployment/17770). The results describe the maximum number of parallel running instances (column **# Containers**) delivering a stable frame rate (column **Avg. FPS**). Running more instances either gives a very high variation in the provided frame rate or is not possible due to other hardware limitations such as system memory, GPU memory etc. +The benchmarks were performed using the `amc benchmark` utility as described in {ref}`howto-run-benchmarks`. The results describe the maximum number of parallel running instances (column **# Containers**) delivering a stable frame rate (column **Avg. FPS**). Running more instances either gives a very high variation in the provided frame rate or is not possible due to other hardware limitations such as system memory, GPU memory etc. For most of the benchmarks below, a special version of the [BombSquad](https://www.froemling.net/apps/bombsquad) application was used. This version runs in a demo mode in which the game provides random and automated simulated gameplay. This allowed the benchmark to simulate a real-world scenario where actual users would play the game, instead of deriving from a static game scene without much variation. @@ -11,7 +14,9 @@ All benchmarks were performed with a variation of the following `amc benchmark` --userdata '{"display_width":1280,"display_height":720,"fps":30,"benchmark":{"enabled":true}}' \ -[note type="information" status="Note"]All benchmarks include rendering and video encoding. On machines/VMs without a GPU, rendering and video encoding are performed in software on the CPU. See [software rendering and video encoding](https://discourse.ubuntu.com/t/17768#software-rendering) for more information.[/note] +```{note} +All benchmarks include rendering and video encoding. On machines/VMs without a GPU, rendering and video encoding are performed in software on the CPU. See {ref}`sec-sw-rendering-video-encoding` for more information. +``` ## Bare metal diff --git a/reference/prometheus.md b/reference/prometheus.md index 2a13b38e..bdb5fbe6 100644 --- a/reference/prometheus.md +++ b/reference/prometheus.md @@ -1,3 +1,6 @@ +(ref-prometheus-metrics)= +# Prometheus metrics + Anbox Cloud gathers various performance metrics that you can access through API endpoints to create a monitoring solution. The following sections list all metrics returned to Prometheus by the Anbox Cloud services that support Prometheus metrics. ## AMS diff --git a/reference/provided-images.md b/reference/provided-images.md index d013ff2f..dedd0b39 100644 --- a/reference/provided-images.md +++ b/reference/provided-images.md @@ -1,3 +1,6 @@ +(ref-provided-images)= +# Provided Anbox Cloud images + Anbox Cloud provides images based on different Android versions and different architectures (amd64, arm64). Anbox Management Service (AMS) manages these images, which can be individually selected by applications. When an image is updated, all applications using the image are automatically updated and rebased on the new image version. Anbox Cloud images are regular [Ubuntu cloud images](https://cloud-images.ubuntu.com/) where Anbox Cloud and its dependencies are installed. Unnecessary packages are removed to improve images size, boot time and security. Officially released images are available from the [official image server](https://images.anbox-cloud.io) hosted by Canonical. It is currently not possible to build custom images for Anbox Cloud. @@ -15,7 +18,6 @@ The following table lists supported images available on the official image serve | `jammy:android12:amd64` | AOSP | 12 | 22.04 | 1.14.0 | | `jammy:android12:arm64` | AOSP | 12 | 22.04 | 1.14.0 | - ## Support for Anbox Cloud images Currently, Anbox Cloud provides images based on Ubuntu 22.04 (jammy). Deprecations, if any, are announced at least two releases in advance. diff --git a/reference/release-notes/1.0.0.md b/reference/release-notes/1.0.0.md index b6a506c0..8c048a5a 100644 --- a/reference/release-notes/1.0.0.md +++ b/reference/release-notes/1.0.0.md @@ -1,6 +1,9 @@ -## 1.0.0 (November 2018) +--- +orphan: true +--- +# 1.0.0 (November 2018) -### New features & improvements +## New features & improvements * First official stable release of the Anbox Cloud stack * Simple deployment via Juju in a single command on any cloud (public, private or bare metal) @@ -20,10 +23,10 @@ * Enabled for binary translation of AArch32 on AArch64 only systems * OpenGL ES 3.x support -### Bug fixes +## Bug fixes None -### Known issues +## Known issues * A few applications freeze after some time and stop rendering. A reason is not known yet and the issue is being investigated. \ No newline at end of file diff --git a/reference/release-notes/1.0.1.md b/reference/release-notes/1.0.1.md index b7d1e323..193e75a5 100644 --- a/reference/release-notes/1.0.1.md +++ b/reference/release-notes/1.0.1.md @@ -1,6 +1,9 @@ -## 1.0.1 (December 2018) +--- +orphan: true +--- +# 1.0.1 (December 2018) -### Bug fixes +## Bug fixes * Applications are not freezing anymore when using OpenGL ES >= 2.x extensively * AArch32 support is now properly detected on AArch64 only machines \ No newline at end of file diff --git a/reference/release-notes/1.1.0.md b/reference/release-notes/1.1.0.md index edf7cb26..c29ae030 100644 --- a/reference/release-notes/1.1.0.md +++ b/reference/release-notes/1.1.0.md @@ -1,6 +1,9 @@ -## 1.1.0 (January 2019) +--- +orphan: true +--- +# 1.1.0 (January 2019) -### New features & improvements +## New features & improvements * The Anbox container is now based on Ubuntu 18.04 * Experimental support for an application registry which serves as a central repository of applications for multiple Anbox Cloud deployments @@ -18,6 +21,6 @@ * AMS can now run on Arm64 machines * Example platform plugin with software rendering and VNC support -### Known issues +## Known issues None \ No newline at end of file diff --git a/reference/release-notes/1.1.1.md b/reference/release-notes/1.1.1.md index a7e3def5..2d75f97c 100644 --- a/reference/release-notes/1.1.1.md +++ b/reference/release-notes/1.1.1.md @@ -1,6 +1,9 @@ -## 1.1.1 (February 2019) +--- +orphan: true +--- +# 1.1.1 (February 2019) -### Bug fixes +## Bug fixes * Anbox was taking an incorrect display size from platform plugins and failed to initialise EGL rendering context. * The Anbox container now always dumps system log files when an error occurred. \ No newline at end of file diff --git a/reference/release-notes/1.10.0.md b/reference/release-notes/1.10.0.md index b950324f..70ecf6b5 100644 --- a/reference/release-notes/1.10.0.md +++ b/reference/release-notes/1.10.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.10.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.10.0 -Please see and [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New Features & Improvements @@ -16,11 +19,11 @@ Android 11 was released back in 2020 by Google and is now available and fully su In earlier Anbox Cloud versions the Juju charms and bundles for Anbox Cloud were only available after explicitly allowing access for user accounts. With 1.10 all charms and bundles are not available in the public on the Juju Charmstore. You can see all available charms and bundles [here](https://charmhub.io/?q=anbox+cloud). -Please note that despite the charms being publicly available you still need a paid subscription for Ubuntu Advantage for Applications. In case you're interested, please [contact us](https://anbox-cloud.io/#request-form). +Please note that despite the charms being publicly available you still need a paid subscription for Ubuntu Advantage for Applications. In case you're interested, please [contact us](https://anbox-cloud.io/contact-us). ### Pinned Package Versions -Before 1.10 a deployment might have been automatically updated through a system package update to the next major or minor version of Anbox Cloud. With 1.10 this is no longer possible and upgrading to a new minor version of Anbox Cloud requires an explicit update to a newer charm as specified in [component versions](https://anbox-cloud.io/docs/component-versions). +Before 1.10 a deployment might have been automatically updated through a system package update to the next major or minor version of Anbox Cloud. With 1.10 this is no longer possible and upgrading to a new minor version of Anbox Cloud requires an explicit update to a newer charm as specified in {ref}`ref-component-versions`. This allows a deployment to stay on a specific release without running into the risk of accidentally updating to a newer version while performing regular system maintenance. @@ -60,13 +63,13 @@ Applications can now be managed from the Anbox Cloud Dashboard. The feature was ### Android 7 -As announced with the [1.9.0 release](https://discourse.ubuntu.com/t/anbox-cloud-1-9-0-has-been-released/20870) Android 7 images are now unsupported. They will stay available till 1.10.1 but will not automatically synced to a new deployment afterwards. +As announced with the [1.9.0 release](1.9.0.md), Android 7 images are now unsupported. They will stay available till 1.10.1 but will not automatically synced to a new deployment afterwards. ### Anbox Stream Gateway Dev UI -The Anbox Stream Gateway Dev UI is now fully replaced with the [Anbox Cloud Dashboard](https://discourse.ubuntu.com/t/20871) and is no longer available. Trying to enable it with the `enable_dev_ui` charm configuration option on the `anbox-stream-gateway` charm will have no effect. +The Anbox Stream Gateway Dev UI is now fully replaced with the {ref}`exp-web-dashboard` and is no longer available. Trying to enable it with the `enable_dev_ui` charm configuration option on the `anbox-stream-gateway` charm will have no effect. -If you haven't deployed the [Anbox Cloud Dashboard](https://discourse.ubuntu.com/t/20871) yet, you can do so with the following commands: +If you haven't deployed the Anbox Cloud Dashboard yet, you can do so with the following commands: $ juju depoy cs:~anbox-charmers/anbox-cloud-dashboard $ juju relate anbox-cloud-dashboard:gateway anbox-stream-gateway:client @@ -107,4 +110,4 @@ The [Juju bundles](https://charmhub.io/?q=anbox+cloud+bundles) for Anbox Cloud a ## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.10.0 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.10.0 release. \ No newline at end of file diff --git a/reference/release-notes/1.10.1.md b/reference/release-notes/1.10.1.md index 7035c0f9..0f0cf315 100644 --- a/reference/release-notes/1.10.1.md +++ b/reference/release-notes/1.10.1.md @@ -1,20 +1,23 @@ -### Introduction +--- +orphan: true +--- +# 1.10.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.10.1. -Please see and [component versions ](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New Features & Improvements +## New Features & Improvements * Properly shut down containers when they are still writing to a ZFS dataset. * Android security updates for May 2021 (see [here](https://source.android.com/security/bulletin/2021-05-01) for more information) -#### Bugs +## Bugs * LP #1926695 Task reaper fails to deleted container because of "target is busy" * LP #1927234 `Sysctl` settings for new LXD nodes are not applied * LP #1927910 Public status endpoint of the appliance returns internal endpoints without authentication * LP #1927342 `wifi-service.odex` is marked as imported but is not found for Android 11 -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.10.1 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.10.1 release. \ No newline at end of file diff --git a/reference/release-notes/1.10.2.md b/reference/release-notes/1.10.2.md index 4789e031..2ac72412 100644 --- a/reference/release-notes/1.10.2.md +++ b/reference/release-notes/1.10.2.md @@ -1,18 +1,21 @@ -### Introduction +--- +orphan: true +--- +# 1.10.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.10.2 -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. **NOTE:** Images will released on Monday, Jun 14 2021 due to pending internal qualification. An update will be provided below this announcement when they become available. -#### New Features & Improvements +## New Features & Improvements * Android security updates for June 2021 (see [here](https://source.android.com/security/bulletin/2021-06-01) for more information) * WebView based on [upstream 90.0.4430.91 release](https://chromereleases.googleblog.com/2021/06/chrome-for-android-update.html) * Android System UI can now be enabled for applications via a new feature flag `enable_system_ui` -#### Bugs +## Bugs * LP #1924715 System gets blocked by `sensorservice` not responding * LP #1926397 Appliance bootstrap log is missing output of various commands @@ -26,6 +29,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * LP #1929151 Appliance storage size is wrong and doesn't reflect the value of snap config `storage.size` * LP #1928703 Silence spammy `eglMakeCurrent` debug message -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.10.2 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.10.2 release. \ No newline at end of file diff --git a/reference/release-notes/1.10.3.md b/reference/release-notes/1.10.3.md index 028dda2c..0a7fc777 100644 --- a/reference/release-notes/1.10.3.md +++ b/reference/release-notes/1.10.3.md @@ -1,20 +1,23 @@ -### Introduction +--- +orphan: true +--- +# 1.10.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.10.3 -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New Features & Improvements +## New Features & Improvements * Android security updates for July 2021 (see [here](https://source.android.com/security/bulletin/2021-07-01) for more information) * WebView based on [upstream 91.0.4472.134 release](https://chromereleases.googleblog.com/2021/06/chrome-for-android-update_0579445428.html) -#### Bugs +## Bugs * LP #1933195 Sensor device doesn't handle sync and guest_sync commands * LP #1932362 [appliance] public address of the LXD node in AMS is not set * LP #1934877 A wrong main activity was used for some APKs -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.10.3 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.10.3 release. \ No newline at end of file diff --git a/reference/release-notes/1.11.0.md b/reference/release-notes/1.11.0.md index fb6be8c9..b2538167 100644 --- a/reference/release-notes/1.11.0.md +++ b/reference/release-notes/1.11.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.11.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.11.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New Features & Improvements @@ -110,4 +113,4 @@ None ## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.11.0 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.11.0 release. \ No newline at end of file diff --git a/reference/release-notes/1.11.1.md b/reference/release-notes/1.11.1.md index e2969dbc..c0273eee 100644 --- a/reference/release-notes/1.11.1.md +++ b/reference/release-notes/1.11.1.md @@ -1,14 +1,17 @@ -### Introduction +--- +orphan: true +--- +# 1.11.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.11.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for August 2021 (see [Android Security Bulletin - August 2021](https://source.android.com/security/bulletin/2021-08-01) for more information) -#### Bugs +## Bugs * LP #1939277 `lxc-attach` fails on sendfile with EINVAL on 5.11 * LP #1938877 Native crash occurred when creating an application from Android 11 after finishing application bootstrap @@ -17,6 +20,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * LP #1939129 The `anbox-stream-sdk.js` file is missing from Android WebView based projects * LP #1938901 Appliance upgrade fails with Juju 2.9.x -#### Upgrade instructions +## Upgrade instructions -See the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions on how to update your Anbox Cloud deployment to the 1.11.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.11.1 release. diff --git a/reference/release-notes/1.11.2.md b/reference/release-notes/1.11.2.md index 00032c8e..bd9cfa85 100644 --- a/reference/release-notes/1.11.2.md +++ b/reference/release-notes/1.11.2.md @@ -1,10 +1,13 @@ -### Introduction +--- +orphan: true +--- +# 1.11.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.11.2. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for September 2021 (see [Android Security Bulletin - September 2021](https://source.android.com/security/bulletin/2021-09-01) for more information) * Android WebView has been updated to [93.0.4577.82](https://chromereleases.googleblog.com/2021/09/chrome-for-android-update.html) @@ -12,7 +15,7 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * Client-side virtual keyboard is now supported on Android 11 * The default instance type of an application in the dashboard is now selected based on the available GPU support -#### Bugs +## Bugs * LP #1938761 Anbox WebView lost focus for unknown reasons and causes client side virtual keyboard hidden in the end * LP #1940807 Failed to launch Anbox sessions with WebRTC platform (`drm` backend) @@ -22,6 +25,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * AC-303 Dashboard lists non active images in application form * AC-342 Connecting second ADB server breaks existing one -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://discourse.ubuntu.com/t/17750) or [Upgrade the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/24186) for instructions on how to update your Anbox Cloud deployment to the 1.11.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.11.2 release. diff --git a/reference/release-notes/1.11.3.md b/reference/release-notes/1.11.3.md index 1db48bfd..9b15fb92 100644 --- a/reference/release-notes/1.11.3.md +++ b/reference/release-notes/1.11.3.md @@ -1,22 +1,25 @@ -### Introduction +--- +orphan: true +--- +# 1.11.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.11.3. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for October 2021 (see [Android Security Bulletin - October 2021](https://source.android.com/security/bulletin/2021-10-01) for more information) * Android WebView has been updated to [94.0.4606.80](https://chromereleases.googleblog.com/2021/10/chrome-for-android-update.html) * The shared memory transport used for the `null` platform is now disabled by default for increased stability * ANGLE libraries used for `null` platform are updated to increase stability and cause Anbox to not crash in certain situations -#### Bugs +## Bugs * AC-321 Deploying multiple AMS units at the same time causes problems * AC-343 ANDROID_EMU_* extensions are visible for Android applications * AC-384 Fix steam view in the dashboard -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.11.3 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.11.3 release. diff --git a/reference/release-notes/1.11.4.md b/reference/release-notes/1.11.4.md index 6148f1d4..9378849e 100644 --- a/reference/release-notes/1.11.4.md +++ b/reference/release-notes/1.11.4.md @@ -1,18 +1,21 @@ -### Introduction +--- +orphan: true +--- +# 1.11.4 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.11.4. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements None. -#### Bugs +## Bugs A bug in the Anbox runtime caused random WebView-based applications to crash when upgrading the `WebView.apk` to [94.0.4606.80](https://chromereleases.googleblog.com/2021/10/chrome-for-android-update.html). For this reason, we downgraded the WebView version to [93.0.4577.82](https://chromereleases.googleblog.com/2021/09/chrome-for-android-update.html) for stability, and we are planning to provide a fix in the Anbox Cloud 1.12 release. -#### Upgrade instructions +## Upgrade instructions This release does not include any charm changes. Only the images are updated, and they are automatically synchronised to your Anbox Cloud deployment via the Canonical image server. See [Manage images](https://anbox-cloud.io/docs/howto/manage/images) for details. diff --git a/reference/release-notes/1.11.5.md b/reference/release-notes/1.11.5.md index d2ff0192..2e68351b 100644 --- a/reference/release-notes/1.11.5.md +++ b/reference/release-notes/1.11.5.md @@ -1,4 +1,7 @@ -### Introduction +--- +orphan: true +--- +# 1.11.5 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.11.5. @@ -6,18 +9,18 @@ This release prepares for an upcoming Ubuntu kernel release on AWS. With the 5.1 Instances running Ubuntu 18.04 (bionic) are not affected, because the latest kernel version for Ubuntu 18.04 is 5.4. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements n/a -#### Bugs +## Bugs * AC-662 Android containers fail to start on Linux 5.13.x -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.11.5 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.11.5 release. diff --git a/reference/release-notes/1.12.0.md b/reference/release-notes/1.12.0.md index 910e1fcc..ec9d50c0 100644 --- a/reference/release-notes/1.12.0.md +++ b/reference/release-notes/1.12.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.12.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.12.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -28,7 +31,7 @@ Reboots are still disallowed by default for Android and must be specifically ena ### Additional life-cycle hooks -Life-cycle hooks inside the Anbox container were extended to provide a more unified list of hooks that are identical between different container types (base, regular). See the [reference](https://discourse.ubuntu.com/t/addons/25293) for an overview of the new hooks. +Life-cycle hooks inside the Anbox container were extended to provide a more unified list of hooks that are identical between different container types (base, regular). See the {ref}`ref-hooks` for an overview of the new hooks. ### Port ranges support in AMS @@ -61,4 +64,4 @@ Containers can now be tagged on launch. The tags are just for informational purp ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.12 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.12 release. diff --git a/reference/release-notes/1.12.1.md b/reference/release-notes/1.12.1.md index 0469a470..0a94651f 100644 --- a/reference/release-notes/1.12.1.md +++ b/reference/release-notes/1.12.1.md @@ -1,14 +1,17 @@ -### Introduction +--- +orphan: true +--- +# 1.12.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.12.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Improved graphics stability on Arm64 machines with NVIDIA GPUs -#### Bugs +## Bugs * AC-472 A native crash occurred to `webview.apk` after upgrading it to 94.0.4606.80 * AC-505 WebRTC platform crashes in `rtc::SocketDispatcher` @@ -18,6 +21,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * AC-553 no Audio output after rejoining a session * AC-555 Telegraf fails to run iptables commands -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.12.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.12.1 release. diff --git a/reference/release-notes/1.12.2.md b/reference/release-notes/1.12.2.md index fcbaf705..e909bd97 100644 --- a/reference/release-notes/1.12.2.md +++ b/reference/release-notes/1.12.2.md @@ -1,17 +1,20 @@ -### Introduction +--- +orphan: true +--- +# 1.12.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.12.2. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Anbox container termination time was shortened by improving internal timeouts * Explicit CUDA context selection on NVIDIA GPUs avoids cross-GPU usage of a single container * Android security updates for December 2021 (see [Android Security Bulletin - December 2021](https://source.android.com/security/bulletin/2021-12-01) for more information) * Android WebView has been updated to [96.0.4664.45](https://chromereleases.googleblog.com/2021/11/stable-channel-update-for-desktop.html) -#### Bugs +## Bugs * AC-313 Dashboard: self signed certificate cause web browser to print a warning * AC-402 Accessing the appliance via the public AWS IP address rather than DNS name breaks streaming @@ -20,6 +23,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * AC-578 Settings app crashes when clicking on "Connected Devices" * AC-580 Android 12: Unhandled netlink message warnings in system log -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.12.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.12.2 release. diff --git a/reference/release-notes/1.12.3.md b/reference/release-notes/1.12.3.md index d8a88873..2b50f60d 100644 --- a/reference/release-notes/1.12.3.md +++ b/reference/release-notes/1.12.3.md @@ -1,15 +1,18 @@ -### Introduction +--- +orphan: true +--- +# 1.12.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.12.3. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for January 2022 (see [Android Security Bulletin - January 2022](https://source.android.com/security/bulletin/2022-01-01) for more information) * Android WebView has been updated to [96.0.4664.45](https://chromereleases.googleblog.com/2021/11/stable-channel-update-for-desktop.html) -#### Bugs +## Bugs * AC-649 Don't return an error if `JoinSession` is called without a body * AC-648 Dashboard ends up with no certificates @@ -20,6 +23,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * AC-621 Anbox shutdown hangs in `anbox::webrtc::metrics::TelegrafBackend::~TelegrafBackend` * AC-559 SurfaceFlinger fails to start at times -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.12.3 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.12.3 release. diff --git a/reference/release-notes/1.12.4.md b/reference/release-notes/1.12.4.md index 7a5f79a4..fb8f4026 100644 --- a/reference/release-notes/1.12.4.md +++ b/reference/release-notes/1.12.4.md @@ -1,19 +1,24 @@ -### Introduction +--- +orphan: true +--- +# 1.12.4 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.12.4. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -[note type="information" status="Note"]This is a bug fix release only for the Anbox Cloud Appliance. Regular Anbox Cloud deployments will not receive an update.[/note] +```{note} +This is a bug fix release only for the Anbox Cloud Appliance. Regular Anbox Cloud deployments will not receive an update. +``` -#### New features & improvements +## New features & improvements None. -#### Bugs +## Bugs * AC-657 Traefik listens on port 8080 for incoming API requests -#### Upgrade instructions +## Upgrade instructions -See [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud Appliance to the 1.12.4 release. \ No newline at end of file +See {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud Appliance to the 1.12.4 release. \ No newline at end of file diff --git a/reference/release-notes/1.12.5.md b/reference/release-notes/1.12.5.md index b65b8b82..9441b62b 100644 --- a/reference/release-notes/1.12.5.md +++ b/reference/release-notes/1.12.5.md @@ -1,4 +1,7 @@ -### Introduction +--- +orphan: true +--- +# 1.12.5 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.12.5. @@ -6,13 +9,13 @@ This release prepares for an upcoming Ubuntu kernel release on AWS. With the 5.1 Instances running Ubuntu 18.04 (bionic) are not affected, because the latest kernel version for Ubuntu 18.04 is 5.4. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements n/a -#### Bugs +## Bugs * AC-676 Launching containers on a specific node fails with "node not found" * AC-671 Application that was signed with a custom system image can't access hidden APIs @@ -20,6 +23,6 @@ n/a * AC-663 Latest Firefox doesn't render in 1.12.x * AC-662 Android containers fail to start on Linux 5.13.x -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.12.5 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.12.5 release. diff --git a/reference/release-notes/1.13.0.md b/reference/release-notes/1.13.0.md index 47246fcf..6864c23c 100644 --- a/reference/release-notes/1.13.0.md +++ b/reference/release-notes/1.13.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.13.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.13.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -85,4 +88,4 @@ n/a ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.13 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.13 release. diff --git a/reference/release-notes/1.13.1.md b/reference/release-notes/1.13.1.md index 4f076b12..78fbb8b8 100644 --- a/reference/release-notes/1.13.1.md +++ b/reference/release-notes/1.13.1.md @@ -1,15 +1,18 @@ -### Introduction +--- +orphan: true +--- +# 1.13.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.13.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for March 2022 (see [Android Security Bulletin - March 2022](https://source.android.com/security/bulletin/2022-03-01) for more information) * Android WebView has been updated to [99.0.4844.58](https://chromereleases.googleblog.com/2022/03/stable-channel-update-for-desktop.html) -#### Bugs +## Bugs * AC-786 Anbox crashes while a Wayland resource is released * AC-780 Appliance fails to deploy when monitoring is disabled @@ -28,6 +31,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * AC-705 AMS suddenly increases memory consumption and causes OOM kill * AC-704 Mesa shader cache directory isn't accessible -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.13.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.13.1 release. diff --git a/reference/release-notes/1.13.2.md b/reference/release-notes/1.13.2.md index 6a1cf252..29a580cb 100644 --- a/reference/release-notes/1.13.2.md +++ b/reference/release-notes/1.13.2.md @@ -1,15 +1,18 @@ -### Introduction +--- +orphan: true +--- +# 1.13.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.13.2. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for April 2022 (see [Android Security Bulletin - April 2022](https://source.android.com/security/bulletin/2022-04-01) for more information) * Android WebView has been updated to [100.0.4896.79](https://chromereleases.googleblog.com/2022/04/chrome-for-android-update.html) -#### Addons - hook timeout +## Addons - hook timeout Addons can now specify an overall timeout for their hooks by setting the `hooks.timeout` key in the `manifest.yaml`. An example `manifest.yaml` will look like @@ -21,11 +24,11 @@ hooks: The timeout will not affect the timeout AMS applies to the overall container bootstrap process. -#### SDK - rotation support +## SDK - rotation support The JavaScript Anbox Streaming SDK now provides a `rotate()` method to tell the Android instance to rotate it's screen. The rotation will be also visually applied to the HTML element containing the stream video. When the stream is rotated input events will be correctly translated. -#### Bugs +## Bugs * AC-830 On a multi GPU system default number of slots is split across all GPUs * AC-829 AMS leaks ports for already removed containers @@ -39,6 +42,6 @@ The JavaScript Anbox Streaming SDK now provides a `rotate()` method to tell the * AC-646 1.12 hooks: $CONTAINER_TYPE is empty for regular containers * AC-827 Failed to create an arm64 based application when Anbox Cloud deployment is capable with multiple architectures -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.13.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.13.2 release. diff --git a/reference/release-notes/1.14.0.md b/reference/release-notes/1.14.0.md index 03e13436..bd3e4f4f 100644 --- a/reference/release-notes/1.14.0.md +++ b/reference/release-notes/1.14.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.14.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.14.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -88,4 +91,4 @@ n/a ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.14 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.14 release. diff --git a/reference/release-notes/1.14.1.md b/reference/release-notes/1.14.1.md index 84380e5c..f8a14a9d 100644 --- a/reference/release-notes/1.14.1.md +++ b/reference/release-notes/1.14.1.md @@ -1,16 +1,19 @@ -### Introduction +--- +orphan: true +--- +# 1.14.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.14.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Android security updates for June 2022 (see [Android Security Bulletin - June 2022](https://source.android.com/security/bulletin/2022-06-01) for more information) * Android WebView has been updated to [102.0.5005.78](https://chromereleases.googleblog.com/2022/05/chrome-for-android-update_28.html) -* The Android [system app installation process](https://discourse.ubuntu.com/t/how-to-install-an-apk-as-a-system-app/27086) now supports the [APK Signature Scheme v2](https://source.android.com/security/apksigning/v2) +* The Android system app installation process now supports the [APK Signature Scheme v2](https://source.android.com/security/apksigning/v2). See {ref}`howto-install-apk-system-app` for more information on the installation process. -#### Bugs +## Bugs * AC-930 AMS doesn't retry stripping a container when LXD returns not matching ETag * AC-936 AMS is misbehaving when LXD cluster fails to process requests @@ -23,6 +26,6 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * AC-818 Show Android boot animation properly * LP #1971945 Anbox Cloud WebRTC handshake failed error -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.14.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.14.1 release. diff --git a/reference/release-notes/1.14.2.md b/reference/release-notes/1.14.2.md index 73fe185c..918c3201 100644 --- a/reference/release-notes/1.14.2.md +++ b/reference/release-notes/1.14.2.md @@ -1,22 +1,25 @@ -### Introduction +--- +orphan: true +--- +# 1.14.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.14.2. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Included Android security updates for July 2022 (see [Android Security Bulletin - July 2022](https://source.android.com/security/bulletin/2022-07-01) for more information). * Updated Android WebView to [103.0.5060.71](https://chromereleases.googleblog.com/2022/07/chrome-for-android-update.html). * [Join URLs](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway/#/session/handle-join-session) handed out by the Anbox Stream Gateway to the Anbox container instances will now not expire anymore. This allows sessions to run forever, if needed. * The Anbox Cloud Appliance now supports deploying behind a HTTP proxy through the `--proxy` argument available for the `anbox-cloud-appliance init` command. -#### Bugs +## Bugs * AC-945 An unhandled exception is raised when starting Anbox * AC-943 No WebRTC metrics data are collected in the Grafana dashboard of the appliance * AC-932 Anbox aborts due to assert in `libsoup` being triggered -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.14.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.14.2 release. diff --git a/reference/release-notes/1.15.0.md b/reference/release-notes/1.15.0.md index b281374e..edca7a65 100644 --- a/reference/release-notes/1.15.0.md +++ b/reference/release-notes/1.15.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.15.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.15.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -12,15 +15,15 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) ### AMS -* AMS now provides support for a [development mode](https://anbox-cloud.io/docs/exp/containers#dev-mode) for containers. This development mode mainly turns off status updates for the Anbox runtime inside a container, which usually cause AMS to stop the container. +* AMS now provides support for a {ref}`sec-dev-mode` for containers. This development mode mainly turns off status updates for the Anbox runtime inside a container, which usually cause AMS to stop the container. * TLS 1.3 is now enforced by default. This means that if you're running older images (< 1.15), they will fail to talk to AMS. You can temporarily enable TLS 1.2 support in AMS again by setting the `force_tls12` [configuration option of the AMS charm](https://charmhub.io/ams/configure?channel=1.15/stable#force_tls12). -* With the new `cpu.limit_mode` configuration, the default strategy that AMS uses to assign CPU time to a container via the Linux kernel scheduler can be changed to use CPU core pinning instead. See [the documentation](https://anbox-cloud.io/docs/exp/performance#container-cpu-access) for more details and the caveats that each mode has. +* With the new `cpu.limit_mode` configuration, the default strategy that AMS uses to assign CPU time to a container via the Linux kernel scheduler can be changed to use CPU core pinning instead. See {ref}`sec-instance-cpu-access` for more details and the caveats that each mode has. * If AMS is behind a load balancer, it can now be configured with the address of the load balancer via the [`load_balancer.url` configuration item](https://anbox-cloud.io/docs/ref/ams-configuration). This configuration will instruct containers to go through the load balancer instead of reaching out to the particular AMS instance that launched them. ### Anbox * The [WebRTC streamer configuration](https://anbox-cloud.io/docs/ref/webrtc-streamer) can now be customised. Currently, only the minimum and the maximum bitrate can be configured, in addition to some options specific to [NVIDIA NvEnc](https://developer.nvidia.com/nvidia-video-codec-sdk). -* [Tracing support](https://anbox-cloud.io/docs/ref/anbox-https-api#heading--10tracing) in Anbox now includes support for tracing the WebRTC stack as well. +* {ref}`Tracing support ` in Anbox now includes support for tracing the WebRTC stack as well. * A new HTTP `/1.0/platform` API allows runtime configuration of the currently loaded platform. For WebRTC, you can now enable RTP trace collection and retrieve information about the current status of the streamer. * Anbox now uses the recently released [LXC 5.0](https://discuss.linuxcontainers.org/t/lxc-5-0-lts-has-been-released/14381). * The WebRTC streamer now allows streaming only audio, only video or neither of them, which can be useful in cases where only the exchange of OOB messages is needed. See the [JS SDK](https://github.com/canonical/anbox-streaming-sdk/blob/master/js/anbox-stream-sdk.js) for details on how to use this feature. @@ -69,4 +72,4 @@ n/a ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.15 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.15 release. diff --git a/reference/release-notes/1.15.1.md b/reference/release-notes/1.15.1.md index 37439cfe..635f906d 100644 --- a/reference/release-notes/1.15.1.md +++ b/reference/release-notes/1.15.1.md @@ -1,21 +1,24 @@ -### Introduction +--- +orphan: true +--- +# 1.15.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.15.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Included Android security updates for September 2022 (see [Android Security Bulletin - September 2022](https://source.android.com/security/bulletin/2022-09-01) for more information). * Updated Android WebView to [105.0.5195.79](https://chromereleases.googleblog.com/2022/09/chrome-for-android-update_5.html). -#### Bugs +## Bugs * AC-1087 Can't delete an application when the application bootstrap ends up in an error state * AC-1079 Not possible to stream container anymore after Android rebooted * AC-1078 No input is possible after rebooting Android * AC-1069 Transport channel closed error occurred when disconnecting a stream on Android client -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.15.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.15.1 release. diff --git a/reference/release-notes/1.15.2.md b/reference/release-notes/1.15.2.md index 6506e2f4..f9444dbf 100644 --- a/reference/release-notes/1.15.2.md +++ b/reference/release-notes/1.15.2.md @@ -1,19 +1,22 @@ -### Introduction +--- +orphan: true +--- +# 1.15.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.15.2. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Included Android security updates for October 2022 (see [Android Security Bulletin - October 2022](https://source.android.com/security/bulletin/2022-10-01) for more information). -#### Bugs +## Bugs * AC-1136 All containers were gone after the appliance snap got refreshed * AC-1130 Cannot reconnect to stream session after client with unsupported video codecs tried * AC-1087 Can't delete an application when the application bootstrap ends up in an error state -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.15.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.15.2 release. diff --git a/reference/release-notes/1.15.3.md b/reference/release-notes/1.15.3.md index 10c0d775..2568dc51 100644 --- a/reference/release-notes/1.15.3.md +++ b/reference/release-notes/1.15.3.md @@ -1,19 +1,22 @@ -### Introduction +--- +orphan: true +--- +# 1.15.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.15.3. Note that this is an out of order release that only applies to the Anbox Cloud Appliance. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Work around a bug in Juju 2.9.35 that prevents the Anbox Cloud Appliance from deploying its software stack entirely. The workaround makes the deployment process independent of the Juju snap that is installed on the host system by including a Juju binary of a previous release inside the appliance snap. -#### Bugs +## Bugs * [LP:1993137](https://bugs.launchpad.net/juju/+bug/1993137) Juju 2.9.35 breaks LXD deployment -#### Upgrade instructions +## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.15.3 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.15.3 release. diff --git a/reference/release-notes/1.16.0.md b/reference/release-notes/1.16.0.md index 6c177c4a..dbd29363 100644 --- a/reference/release-notes/1.16.0.md +++ b/reference/release-notes/1.16.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.16.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.16.0. -Please see the [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see the {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -30,7 +33,7 @@ With the introduction of support for Android 13, Anbox Cloud now separates the ` #### New bug report utility -The Anbox [images](https://anbox-cloud.io/docs/ref/provided-images) include a new bug report tool called `anbox-bug-report`, which is extensible and collects information in an archive rather than a file. This method allows developers and support to easier inspect the information when debugging issues. See the [documentation](https://discourse.ubuntu.com/t/how-to-troubleshoot-anbox-cloud/17837) for more details. +The Anbox [images](https://anbox-cloud.io/docs/ref/provided-images) include a new bug report tool called `anbox-bug-report`, which is extensible and collects information in an archive rather than a file. This method allows developers and support to easier inspect the information when debugging issues. See {ref}`howto-ts-anbox-cloud` for more information. ### WebRTC streaming improvements @@ -44,7 +47,7 @@ To allow better fine-tuning of the WebRTC based streaming implementation in Anbo ### Data channel v2 -[Version 2 of the OOB data exchange protocol](https://anbox-cloud.io/docs/howto/stream/oob-data#version-2-1), which Anbox Cloud introduced in version 1.15, provides a full-duplex bidirectional data transmission between the Android container and the WebRTC client. In the 1.16 release, Anbox Cloud introduces the Anbox WebRTC data proxy service as an extension to version 2 of the OOB data. The data proxy service exposes a binder service in the Android container that can be used by an Android application to communicate with a WebRTC client over the Anbox WebRTC platform. +{ref}`Version 2 of the OOB data exchange protocol `, which Anbox Cloud introduced in version 1.15, provides a full-duplex bidirectional data transmission between the Android container and the WebRTC client. In the 1.16 release, Anbox Cloud introduces the Anbox WebRTC data proxy service as an extension to version 2 of the OOB data. The data proxy service exposes a binder service in the Android container that can be used by an Android application to communicate with a WebRTC client over the Anbox WebRTC platform. ### Ubuntu 22.04 support @@ -77,7 +80,7 @@ A new AMS charm configuration `use_network_acl` has been added. This configurati ## Deprecations * The Anbox [LXD images](https://anbox-cloud.io/docs/ref/provided-images) based on the Ubuntu 18.04 (bionic) release are now deprecated. They will receive their last update with the Anbox Cloud 1.18 release in May 2023. We strongly recommend to upgrade to the Ubuntu 22.04 (jammy) based images, which will be supported until May 2025. These images provide the exact same functionality but are based on a newer release of Ubuntu, which might require small adjustments in addons or customisations. -* The support for [version 1 of the OOB data exchange protocol](https://anbox-cloud.io/docs/howto/stream/oob-data#version-1-10), which allows only half-duplex data transmission, has been removed in the Anbox Cloud 1.16 release. With [version 2 of the OOB data exchange protocol](https://anbox-cloud.io/docs/howto/stream/oob-data#version-2-1), Anbox Cloud supports full-duplex bidirectional data transmission. We recommend to migrate your integration of version 1 of the out-of-band data exchange to version 2 for full-duplex data transmission and better performance. +* The support for {ref}`version 1 of the OOB data exchange protocol `, which allows only half-duplex data transmission, has been removed in the Anbox Cloud 1.16 release. With {ref}`version 2 of the OOB data exchange protocol `, Anbox Cloud supports full-duplex bidirectional data transmission. We recommend to migrate your integration of version 1 of the out-of-band data exchange to version 2 for full-duplex data transmission and better performance. ## Known issues @@ -97,4 +100,4 @@ n/a ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.16 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.16 release. diff --git a/reference/release-notes/1.16.1.md b/reference/release-notes/1.16.1.md index 66472159..c8e47701 100644 --- a/reference/release-notes/1.16.1.md +++ b/reference/release-notes/1.16.1.md @@ -1,15 +1,18 @@ -### Introduction +--- +orphan: true +--- +# 1.16.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.16.1. -Please see the [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see the {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Included Android security updates for December 2022 (see [Android Security Bulletin - December 2022](https://source.android.com/security/bulletin/2022-12-01) for more information). * Updated Android WebView to [108.0.5359.79](https://chromereleases.googleblog.com/2022/12/chrome-for-android-update.html). -#### Bugs +## Bugs * AC-1222 `ext4` online metadata check service is active but should not be * AC-1229 Appliance bootstrap doesn't fail when an Juju unit ends up in an error status @@ -20,4 +23,4 @@ Please see the [component versions](https://anbox-cloud.io/docs/component-versio ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.16.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.16.1 release. diff --git a/reference/release-notes/1.16.2.md b/reference/release-notes/1.16.2.md index 71b1cf28..bfd73d38 100644 --- a/reference/release-notes/1.16.2.md +++ b/reference/release-notes/1.16.2.md @@ -1,15 +1,18 @@ -### Introduction +--- +orphan: true +--- +# 1.16.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.16.2. -Please see the [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see the {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements * Included Android security updates for January 2023 (see [Android Security Bulletin - January 2023](https://source.android.com/security/bulletin/2023-01-01) for more information). * Updated Android WebView to [108.0.5359.128](https://chromereleases.googleblog.com/2022/12/chrome-for-android-update_13.html). -#### Bugs +## Bugs * AC-1276 `finalrd.service`: Failed with result 'exit-code'. * AC-1277 The pre-start/install hook to modify Android's root file system always failed @@ -17,4 +20,4 @@ Please see the [component versions](https://anbox-cloud.io/docs/component-versio ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.16.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.16.2 release. diff --git a/reference/release-notes/1.16.3.md b/reference/release-notes/1.16.3.md index c6367ddf..f6866f4e 100644 --- a/reference/release-notes/1.16.3.md +++ b/reference/release-notes/1.16.3.md @@ -1,4 +1,7 @@ -### Introduction +--- +orphan: true +--- +# 1.16.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.16.3. This release updates only the Anbox Cloud Appliance. However, if you run the regular Anbox Cloud and have Grafana deployed, an action is required (see below). @@ -10,16 +13,16 @@ If the user chooses to add support for monitoring during the initialisation of t If you deployed the regular Anbox Cloud and installed [the Grafana charm yourself](https://charmhub.io/grafana), update the [`install_keys` configuration item](https://charmhub.io/grafana/configure#install_keys) to provide the new GPG signing key to the installation. -Please see the [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see the {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements n/a -#### Bugs +## Bugs * [LP #2002776](https://bugs.launchpad.net/charm-grafana/+bug/2002776): Grafana APT repository key was rotated and charm needs to adapt ## Upgrade instructions -See [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud Appliance deployment to the 1.16.3 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud Appliance deployment to the 1.16.3 release. diff --git a/reference/release-notes/1.16.4.md b/reference/release-notes/1.16.4.md index 222b6f4b..0423a1b1 100644 --- a/reference/release-notes/1.16.4.md +++ b/reference/release-notes/1.16.4.md @@ -1,19 +1,22 @@ -### Introduction +--- +orphan: true +--- +# 1.16.4 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.16.4. This is an out-of-order release to mitigate a bug found with newer versions of LXD, specifically the 5.0.2 update to the 5.0 LTS release series. The bug prevents containers from starting when LXD 5.0.2 is installed. If you're running LXD 5.0.2, you must update the Anbox image that you're using. -Please see the [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see the {ref}`ref-component-versions` for a list of updated components. -#### New features & improvements +## New features & improvements n/a -#### Bugs +## Bugs * AC-1320 Anbox containers fail to start with LXD 5.0.2 ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.16.4 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.16.4 release. diff --git a/reference/release-notes/1.17.0.md b/reference/release-notes/1.17.0.md index e6a6e684..0ae78635 100644 --- a/reference/release-notes/1.17.0.md +++ b/reference/release-notes/1.17.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.17.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.17.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -16,7 +19,7 @@ As of Anbox Cloud 1.17, support is still kept behind a feature flag and is curre ### Dynamic screen resolution -Anbox Cloud allows changing the screen resolution of already running Android instances. This is helpful especially when containers are being used for clients with different display aspect ratios to avoid letter boxing. Internally, the Anbox runtime will reconfigure the Android display with the new resolution and afterwards the encoded video stream will match the new resolution. Changing the display resolution is possible at the time of connection via the [`/1.0/sessions//join` API endpoint]([https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway/](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway/#/session/handle-join-session)) of the Anbox Stream Gateway. +Anbox Cloud allows changing the screen resolution of already running Android instances. This is helpful especially when containers are being used for clients with different display aspect ratios to avoid letter boxing. Internally, the Anbox runtime will reconfigure the Android display with the new resolution and afterwards the encoded video stream will match the new resolution. Changing the display resolution is possible at the time of connection via the [`/1.0/sessions//join` API endpoint](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway/#/session/handle-join-session) of the Anbox Stream Gateway. ### Start and stop support for containers @@ -75,4 +78,4 @@ This will be further enhanced in future releases to allow easy modification of n ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.17 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.17 release. diff --git a/reference/release-notes/1.17.1.md b/reference/release-notes/1.17.1.md index c6651100..72804489 100644 --- a/reference/release-notes/1.17.1.md +++ b/reference/release-notes/1.17.1.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.17.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.17.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -22,9 +25,9 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * Since Android 10 will no longer receive security patches from Google starting this month, the security patch level for Android 10 should be 2023-02-05 rather than 2023-03-05. This will be fixed in the Anbox Cloud 1.17.2 release. * The following two commits from the [latest security tag](https://android.googlesource.com/platform/frameworks/base/+/refs/tags/android-security-11.0.0_r65) are not yet applied. They will be applied in the 1.17.2 release. - - https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e - - https://android.googlesource.com/platform/frameworks/base/+/523926b137a69b3a12da18b66dfd24afbf00f445 + - [`https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e`](https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e) + - [`https://android.googlesource.com/platform/frameworks/base/+/523926b137a69b3a12da18b66dfd24afbf00f445`](https://android.googlesource.com/platform/frameworks/base/+/523926b137a69b3a12da18b66dfd24afbf00f445) ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.17.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.17.1 release. diff --git a/reference/release-notes/1.17.2.md b/reference/release-notes/1.17.2.md index db7dbe75..745ac86d 100644 --- a/reference/release-notes/1.17.2.md +++ b/reference/release-notes/1.17.2.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.17.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.17.2. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -21,8 +24,8 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) * [AC-1493](https://warthogs.atlassian.net/browse/AC-1493) The Grafana Anbox Cloud dashboard shows inflated metrics when there are multiple AMS nodes. * The known issue in Anbox Cloud 1.17.1 that the security patch level for Android 10 was 2023-03-05 instead of 2023-02-05 has been fixed. * For Android 11, the following two commits from the [latest security tag](https://android.googlesource.com/platform/frameworks/base/+/refs/tags/android-security-11.0.0_r65) are applied: - - https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e - - https://android.googlesource.com/platform/frameworks/base/+/523926b137a69b3a12da18b66dfd24afbf00f445 + - [`https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e`](https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e) + - [`https://android.googlesource.com/platform/frameworks/base/+/523926b137a69b3a12da18b66dfd24afbf00f445`](https://android.googlesource.com/platform/frameworks/base/+/0340c219c094cbd0a07600eac471cfeeaceba60e) ## Known issues @@ -31,4 +34,4 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.17.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.17.2 release. diff --git a/reference/release-notes/1.18.0.md b/reference/release-notes/1.18.0.md index c232a7b0..2a37fabc 100644 --- a/reference/release-notes/1.18.0.md +++ b/reference/release-notes/1.18.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.18.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.18.0. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -67,4 +70,4 @@ The following issues are known to occur with the 1.18.0 version of Anbox Cloud a ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.18 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.18 release. diff --git a/reference/release-notes/1.18.1.md b/reference/release-notes/1.18.1.md index ae42680b..801f4de2 100644 --- a/reference/release-notes/1.18.1.md +++ b/reference/release-notes/1.18.1.md @@ -1,7 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.18.1 + The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.18.1. -Please see [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements * Android security updates for June 2023 (See [Android Security Bulletin - June 2023](https://source.android.com/docs/security/bulletin/2023-06-01) for more information). @@ -24,4 +28,4 @@ Please see [component versions](https://anbox-cloud.io/docs/component-versions) ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.18.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.18.1 release. diff --git a/reference/release-notes/1.18.2.md b/reference/release-notes/1.18.2.md index 8beb9528..f62c1b2f 100644 --- a/reference/release-notes/1.18.2.md +++ b/reference/release-notes/1.18.2.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.18.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.18.2. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements * Android security updates for July 2023. See [Android Security Bulletin - July 2023](https://source.android.com/docs/security/bulletin/2023-07-01) for more information. @@ -32,4 +35,4 @@ Otherwise, Anbox containers will fail to communicate with the stream agent. ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-loud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.18.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.18.2 release. diff --git a/reference/release-notes/1.19.0-fix1.md b/reference/release-notes/1.19.0-fix1.md index 3c146142..60a02fc1 100644 --- a/reference/release-notes/1.19.0-fix1.md +++ b/reference/release-notes/1.19.0-fix1.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- +# Release notes for 1.19.0-fix1 hotfix + The Anbox Cloud team has released a hotfix (1.19.0-fix1) to address the [Grafana security update](https://grafana.com/blog/2023/08/24/grafana-security-update-gpg-signing-key-rotation/). The hotfix applies the updated `apt` key for Grafana. Monitoring with Grafana is enabled by default in the Anbox Cloud Appliance and hence without the hotfix, new installations of the Appliance may fail. diff --git a/reference/release-notes/1.19.0.md b/reference/release-notes/1.19.0.md index 1889a699..df073966 100644 --- a/reference/release-notes/1.19.0.md +++ b/reference/release-notes/1.19.0.md @@ -1,14 +1,17 @@ -## Introduction +--- +orphan: true +--- +# 1.19.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.19.0. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements ### Core stack improvements -* The Anbox Management Service (AMS) API documentation created using OpenAPI specification (Swagger 2.0) is available on the AMS host at `/1.0/swagger.json` and at https://canonical.github.io/anbox-cloud.github.com/latest/ams/. +* The Anbox Management Service (AMS) API documentation created using OpenAPI specification (Swagger 2.0) is available on the AMS host at `/1.0/swagger.json` and at [`https://canonical.github.io/anbox-cloud.github.com/latest/ams/`](https://canonical.github.io/anbox-cloud.github.com/latest/ams/). * Pagination and filtering support is enabled for containers and applications in the AMS API. You can use it by directly interacting with the AMS using API calls. * A cgroup v1 emulation layer is added for cgroup v2-only hosts. This is required by Android for resource tracking and management. * Enhanced configuration of failure domain of LXD nodes to ensure LXD makes its database highly available across multiple availability zones. @@ -86,4 +89,4 @@ e2scrub_reap.service ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.19.0 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.19.0 release. diff --git a/reference/release-notes/1.19.1.md b/reference/release-notes/1.19.1.md index c4df4d9c..627c2567 100644 --- a/reference/release-notes/1.19.1.md +++ b/reference/release-notes/1.19.1.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.19.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.19.1. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -35,4 +38,4 @@ Please see [component versions](https://anbox-cloud.io/docs/ref/component-versio ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.19.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.19.1 release. diff --git a/reference/release-notes/1.19.2.md b/reference/release-notes/1.19.2.md index b092a675..d5bc6b0c 100644 --- a/reference/release-notes/1.19.2.md +++ b/reference/release-notes/1.19.2.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.19.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.19.2. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -23,4 +26,4 @@ Please see [component versions](https://anbox-cloud.io/docs/ref/component-versio ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.19.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.19.2 release. diff --git a/reference/release-notes/1.2.0.md b/reference/release-notes/1.2.0.md index 4ee4e81e..9ceddfac 100644 --- a/reference/release-notes/1.2.0.md +++ b/reference/release-notes/1.2.0.md @@ -1,6 +1,9 @@ -## 1.2.0 (April 2019) +--- +orphan: true +--- +# 1.2.0 (April 2019) -### New features & improvements +## New features & improvements * Full support for an [Application Registry](installation-registry.md) * Updated Android 7.x with all [security patches](https://source.android.com/security/bulletin) as of Mar 5 2019 diff --git a/reference/release-notes/1.2.1.md b/reference/release-notes/1.2.1.md index 901dbf31..d75e1e3e 100644 --- a/reference/release-notes/1.2.1.md +++ b/reference/release-notes/1.2.1.md @@ -1,6 +1,9 @@ -## 1.2.1 (April 2019) +--- +orphan: true +--- +# 1.2.1 (April 2019) -### Bug fixes +## Bug fixes * Telegraf was restarted every five minutes which caused metrics from Anbox being lost. * Android framework crashed in [`WifiManager.getWifiState()`](https://developer.android.com/reference/android/net/wifi/WifiManager.html#getWifiState()) diff --git a/reference/release-notes/1.20.0.md b/reference/release-notes/1.20.0.md index 829f62e5..67043567 100644 --- a/reference/release-notes/1.20.0.md +++ b/reference/release-notes/1.20.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.20.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.20.0. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -39,11 +42,11 @@ With the 1.20.0 release, we have made the following improvements to the web dash * Android security updates for November 2023 (see [Android Security Bulletin - November 2023](https://source.android.com/docs/security/bulletin/2023-11-01) for more information). * The Android WebView has been updated to [119.0.6045.66](https://chromereleases.googleblog.com/2023/10/early-stable-update-for-android_01005299231.html). -* We have modernised the existing NATS charm to align with best practices in developing charms. The new NATS charm is available at https://charmhub.io/nats. The 1.21.0 release of Anbox Cloud will automatically upgrade to the new charm. +* We have modernised the existing NATS charm to align with best practices in developing charms. The new NATS charm is available at [`https://charmhub.io/nats`](https://charmhub.io/nats). The 1.21.0 release of Anbox Cloud will automatically upgrade to the new charm. ## Deprecations -* The [`instance-type` attribute](https://discourse.ubuntu.com/t/24197#instance-type-1) is deprecated now. You can use the `resources` attribute to specify any custom resource requirements. +* The {ref}`sec-application-manifest-instance-type` attribute is deprecated now. You can use the `resources` attribute to specify any custom resource requirements. Also, in the Anbox Cloud documentation, the use of the term *Instance type* to indicate a set of resources is deprecated and will be completely removed in the future releases. Instead, the term *Resource preset* is used to indicate a set of resources available for an instance. @@ -63,4 +66,4 @@ The following bugs are fixed in the Anbox Cloud 1.20 version: ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.20 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.20 release. diff --git a/reference/release-notes/1.20.1.md b/reference/release-notes/1.20.1.md index bebeee6a..e4d86c63 100644 --- a/reference/release-notes/1.20.1.md +++ b/reference/release-notes/1.20.1.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.20.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.20.1. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -38,4 +41,4 @@ apt install --no-install-recommends -y libgl1-mesa-dri ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.20.1 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.20.1 release. \ No newline at end of file diff --git a/reference/release-notes/1.20.2.md b/reference/release-notes/1.20.2.md index d3fb1c6f..1fcd06c6 100644 --- a/reference/release-notes/1.20.2.md +++ b/reference/release-notes/1.20.2.md @@ -1,7 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.20.2 + The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.20.2. -Please see [component versions](https://anbox-cloud.io/docs/ref/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements * VPU slots for an app are synchronised through the Anbox Application Registry (AAR). @@ -20,4 +24,4 @@ Please see [component versions](https://anbox-cloud.io/docs/ref/component-versio * [Bug report](https://discourse.ubuntu.com/t/enable-webgl-in-anbox-cloud/41170/4) When running WebGL based applications, the WebView shows an error and indicates that the WebView APK shipped as part of the Android image does not support WebGL. ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.20.2 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.20.2 release. diff --git a/reference/release-notes/1.21.0.md b/reference/release-notes/1.21.0.md index 1a47a594..c7ec9bff 100644 --- a/reference/release-notes/1.21.0.md +++ b/reference/release-notes/1.21.0.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.21.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.21.0. -Please see [component versions](https://anbox-cloud.io/docs/reference/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -16,13 +19,13 @@ The 1.21.0 release of Anbox Cloud brings the following features and improvements This release also provides [Renderdoc](https://github.com/baldurk/renderdoc) support for debugging purposes. See [Graphics debugging with renderdoc](https://anbox-cloud.io/docs/howto/android/graphics-debugging-with-renderdoc) for more information. * The NVIDIA UDA driver variant with version 545 or later can be installed with the Anbox Cloud Appliance by using the `nvidia-driver-series` and `use-nvidia-uda-driver` flags with the `anbox-cloud-appliance init` command. -* GL Async swap support is disabled by default. See [GL Async swap support](https://discourse.ubuntu.com/t/supported-features-aosp-vs-aaos/42520) for more information. +* GL Async swap support is disabled by default. See {ref}`sec-gl-async-swap` for more information. * In the [AMS HTTP API](https://canonical.github.io/anbox-cloud.github.com/latest/ams/), `/1.0` endpoint exposes the cluster ID and name to enable identifying a subcluster. * The [Anbox Cloud NFS operator](https://github.com/canonical/anbox-cloud-nfs-operator) charm now supports mounting EFS file system on AWS when you require Transport Layer Security (TLS). With an EFS file system, you can [configure](https://github.com/canonical/anbox-cloud-nfs-operator/blob/main/config.yaml) the charm with the following parameters: - `mount_type` set to `efs` - `nfs_extra_options` set to `tls` * The Anbox Application Registry(AAR) can make use of Identity and Access Management(IAM) roles applied to an AWS instance using instance profiles. This relieves you from having to configure an access key/secret for instances. For information on how to use an IAM role in AAR, see [how to deploy AAR](https://anbox-cloud.io/docs/howto/aar/deploy). -* The NATS charm is switched from its [older version](https://charmhub.io/nats-charmers-nats) to a [newer version](https://charmhub.io/nats) on Charmhub. This would require that you switch to the new charm source. For more information, see [How to upgrade Anbox Cloud](https://discourse.ubuntu.com/t/how-to-upgrade-anbox-cloud/17750). +* The NATS charm is switched from its [older version](https://charmhub.io/nats-charmers-nats) to a [newer version](https://charmhub.io/nats) on Charmhub. This would require that you switch to the new charm source. For more information, see {ref}`howto-upgrade-anbox-cloud`. ### Dashboard improvements @@ -61,4 +64,4 @@ The following improvements are available in the Anbox Cloud dashboard for this r ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.21.0 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.21.0 release. diff --git a/reference/release-notes/1.21.1.md b/reference/release-notes/1.21.1.md index 1ab2a171..c09d7bd4 100644 --- a/reference/release-notes/1.21.1.md +++ b/reference/release-notes/1.21.1.md @@ -1,8 +1,11 @@ -## Introduction +--- +orphan: true +--- +# 1.21.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.21.1. -Please see [component versions](https://anbox-cloud.io/docs/reference/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. ## New features & improvements @@ -22,4 +25,4 @@ Please see [component versions](https://anbox-cloud.io/docs/reference/component- ## Upgrade instructions -See [Upgrade Anbox Cloud](https://anbox-cloud.io/docs/howto/update/upgrade-anbox) or [Upgrade the Anbox Cloud Appliance](https://anbox-cloud.io/docs/howto/update/upgrade-appliance) for instructions on how to update your Anbox Cloud deployment to the 1.21.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions on how to update your Anbox Cloud deployment to the 1.21.1 release. diff --git a/reference/release-notes/1.21.2.md b/reference/release-notes/1.21.2.md index 0f598e92..e12232c1 100644 --- a/reference/release-notes/1.21.2.md +++ b/reference/release-notes/1.21.2.md @@ -1,4 +1,7 @@ -## Introduction +--- +orphan: true +--- +# 1.21.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.21.2. diff --git a/reference/release-notes/1.22.0.md b/reference/release-notes/1.22.0.md index 61b4839b..0733a75c 100644 --- a/reference/release-notes/1.22.0.md +++ b/reference/release-notes/1.22.0.md @@ -1,4 +1,7 @@ -## Introduction +--- +orphan: true +--- +# 1.22.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.22.0. @@ -15,7 +18,7 @@ The 1.22.0 release of Anbox Cloud brings the following features and improvements * VHAL enhancements: - Configuration returned by the APIs have a new field containing a name and a list of area names for the standard VHAL properties. - Property values returned by the APIs have a new field containing a list of area names for the standard VHAL properties. - - You can replace the Anbox Cloud VHAL implementation with your custom implementation for AAOS images. See [How to use a custom VHAL implementation](https://discourse.ubuntu.com/t/replace-the-anbox-vhal/45070). + - You can replace the Anbox Cloud VHAL implementation with your custom implementation for AAOS images. See [How to use a custom VHAL implementation](https://anbox-cloud.io/docs/howto/android/custom_vhal). ### Streaming stack improvements @@ -40,13 +43,13 @@ The following improvements are available in the Anbox Cloud dashboard for this r ### Other -* Support for building custom images of Anbox Cloud based on AAOS. See [Custom images](https://discourse.ubuntu.com/t/custom-images/45071). +* Support for building custom images of Anbox Cloud based on AAOS. See [Custom images](https://anbox-cloud.io/docs/explanation/custom-images). * Android security updates for May 2024 (see [Android Security Bulletin - May 2024](https://source.android.com/docs/security/bulletin/2024-05-01) for more information). * The Android WebView has been updated to [124.0.6367.82](https://chromereleases.googleblog.com/2024/04/chrome-for-android-update_24.html). ## Deprecations -See [Deprecation notices](https://discourse.ubuntu.com/t/deprecation-notices/45073) for a list of deprecations in this release. +See [Deprecation notices](https://anbox-cloud.io/docs/reference/deprecation-notices) for a list of deprecations in this release. ## Removed functionality diff --git a/reference/release-notes/1.22.1.md b/reference/release-notes/1.22.1.md index dc33f69a..3da6fbd6 100644 --- a/reference/release-notes/1.22.1.md +++ b/reference/release-notes/1.22.1.md @@ -1,4 +1,7 @@ -## Introduction +--- +orphan: true +--- +# 1.22.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.22.1. diff --git a/reference/release-notes/1.3.0.md b/reference/release-notes/1.3.0.md index 2e93438a..92b47999 100644 --- a/reference/release-notes/1.3.0.md +++ b/reference/release-notes/1.3.0.md @@ -1,6 +1,9 @@ -## 1.3.0 (August 2019) +--- +orphan: true +--- +# 1.3.0 (August 2019) -### New features & improvements +## New features & improvements * Images are now only distributed via the official image server and no longer available for download * The application registry received a dedicated CLI command to manage trusted clients diff --git a/reference/release-notes/1.3.1.md b/reference/release-notes/1.3.1.md index 0f85021f..0113dce5 100644 --- a/reference/release-notes/1.3.1.md +++ b/reference/release-notes/1.3.1.md @@ -1,13 +1,16 @@ -## 1.3.1 (September 2019) +--- +orphan: true +--- +# 1.3.1 (September 2019) -### New features & improvements +## New features & improvements * Allow underlying image of an application to be changed * Support for applications without an APK * An Anbox platform can now specify the display refresh rate * Integrated Android security fixes for August 2019. See the [Android Security Bulletins](https://source.android.com/security/bulletin) for more information. -### Bug fixes +## Bug fixes * Refresh the LXD snap on demand when the configuration is changed * Don't use embedded etcd when a real etcd is available diff --git a/reference/release-notes/1.3.2.md b/reference/release-notes/1.3.2.md index 828242a2..0ab5793d 100644 --- a/reference/release-notes/1.3.2.md +++ b/reference/release-notes/1.3.2.md @@ -1,4 +1,7 @@ -### New features & improvements +--- +orphan: true +--- +# New features & improvements * Increased maximum allowed startup time for containers to 15 minutes * Containers can now started with additional disk space added diff --git a/reference/release-notes/1.3.3.md b/reference/release-notes/1.3.3.md index ca474080..94a4e324 100644 --- a/reference/release-notes/1.3.3.md +++ b/reference/release-notes/1.3.3.md @@ -1,6 +1,9 @@ -## 1.3 (January 2020) +--- +orphan: true +--- +# 1.3 (January 2020) -### New features & improvements +## New features & improvements * Generating thumbnails within `libstagefright` in the Android 7 images is now working reliable where it was generating single coloured images at times before. * Error messages are now presented via the AMS REST API for application versions. diff --git a/reference/release-notes/1.4.0.md b/reference/release-notes/1.4.0.md index cac29784..cb566e4d 100644 --- a/reference/release-notes/1.4.0.md +++ b/reference/release-notes/1.4.0.md @@ -1,6 +1,9 @@ -## 1.4.0 (March 2020) +--- +orphan: true +--- +# 1.4.0 (March 2020) -### New features & improvements +## New features & improvements * Support for Android 10 including latest security updates * Inclusion of an alpha version of the WebRTC based Streaming Stack diff --git a/reference/release-notes/1.5.0.md b/reference/release-notes/1.5.0.md index 0a5adc47..d7e88e89 100644 --- a/reference/release-notes/1.5.0.md +++ b/reference/release-notes/1.5.0.md @@ -1,6 +1,9 @@ -## 1.5.0 (April 2020) +--- +orphan: true +--- +# 1.5.0 (April 2020) -### New features & improvements +## New features & improvements * Support for Android 10 including latest security updates * Updated software rendering to work on Android 10 @@ -14,6 +17,6 @@ * Software rendering and video encoding support for the streaming stack * GPUs are now identified by their PCI address in order for a correct mapping inside containers -### Deprecations +## Deprecations * Android 7 images are now deprecated and will be dropped with the next release of Anbox Cloud \ No newline at end of file diff --git a/reference/release-notes/1.5.1.md b/reference/release-notes/1.5.1.md index 4fab3b3b..93d32121 100644 --- a/reference/release-notes/1.5.1.md +++ b/reference/release-notes/1.5.1.md @@ -1,6 +1,9 @@ -## 1.5.1 (May 2020) +--- +orphan: true +--- +# 1.5.1 (May 2020) -### New features & improvements +## New features & improvements * Fix timeout issue when adding or removing LXD nodes from the cluster in AMS * Containers are now gracefully terminated to ensure the backup hook is executed diff --git a/reference/release-notes/1.5.2.md b/reference/release-notes/1.5.2.md index 72b8b0c5..c08b9261 100644 --- a/reference/release-notes/1.5.2.md +++ b/reference/release-notes/1.5.2.md @@ -1,6 +1,9 @@ -## 1.5.2 (June 2020) +--- +orphan: true +--- +# 1.5.2 (June 2020) -### New features & improvements +## New features & improvements * Fix infinite loading screen issue when streaming from Anbox Stream Gateway UI * Fix SDK documentation for Anbox Stream Gateway and all API routes are prefixed with "/1.0" diff --git a/reference/release-notes/1.6.0.md b/reference/release-notes/1.6.0.md index c4e02ad4..477838d3 100644 --- a/reference/release-notes/1.6.0.md +++ b/reference/release-notes/1.6.0.md @@ -1,6 +1,9 @@ -## 1.6.0 (June 2020) +--- +orphan: true +--- +# 1.6.0 (June 2020) -### New features & improvements +## New features & improvements * Watchdog can now be disabled via the application manifest or configured to allow additional packages to provide a foreground activity * Service endpoints can now be defined in the application manifest diff --git a/reference/release-notes/1.6.1.md b/reference/release-notes/1.6.1.md index 096a4b37..df8a76b3 100644 --- a/reference/release-notes/1.6.1.md +++ b/reference/release-notes/1.6.1.md @@ -1,6 +1,9 @@ -## 1.6.1 (June 2020) +--- +orphan: true +--- +# 1.6.1 (June 2020) -### Bug fixes +## Bug fixes * LP #1885257: Fix high CPU usage for Anbox daemon * LP #1885972: Fix watchdog, services and video encoder settings out of sync when updating an application \ No newline at end of file diff --git a/reference/release-notes/1.6.2.md b/reference/release-notes/1.6.2.md index 69f04eee..556ad8df 100644 --- a/reference/release-notes/1.6.2.md +++ b/reference/release-notes/1.6.2.md @@ -1,10 +1,13 @@ -## 1.6.2 (June 2020) +--- +orphan: true +--- +# 1.6.2 (June 2020) -### New features & improvements +## New features & improvements * Applications without an APK can now specify a boot activity in their application manifest -### Bug fixes +## Bug fixes * LP #1885107: Automatic application updates were missing configured resources, watchdog or service information * LP #1885257: `anboxd` was using 100% of a single CPU core due to a spinning loop \ No newline at end of file diff --git a/reference/release-notes/1.6.3.md b/reference/release-notes/1.6.3.md index 821b7b14..786e3520 100644 --- a/reference/release-notes/1.6.3.md +++ b/reference/release-notes/1.6.3.md @@ -1,5 +1,8 @@ -## 1.6.3 (July 2020) +--- +orphan: true +--- +# 1.6.3 (July 2020) -### Bug fixes +## Bug fixes * LP #1885726: Fix the mouse and touch displacement issue for Anbox Stream Gateway UI \ No newline at end of file diff --git a/reference/release-notes/1.7.0.md b/reference/release-notes/1.7.0.md index 1d3c3d09..26c6d899 100644 --- a/reference/release-notes/1.7.0.md +++ b/reference/release-notes/1.7.0.md @@ -1,6 +1,9 @@ -## 1.7.0 (August 2020) +--- +orphan: true +--- +# 1.7.0 (August 2020) -### New features & improvements +## New features & improvements * Anbox Cloud is now fully integrated with [Ubuntu Advantage](https://ubuntu.com/advantage) * TLS certificates are now managed through a common CA for all components ([Easy-RSA](https://charmhub.io/containers-easyrsa)) @@ -9,12 +12,11 @@ * Allow streams started via the stream gateway UI to use 1080p as display resolution * Deprecated the Anbox Cloud Doctor in favour of [Juju crashdump](https://github.com/juju/juju-crashdump) -### Bug fixes +## Bug fixes * LP #1890573: Always delete the base container even when an application failed to be bootstrapped * LP #1847226 Fixed a bug that prevented the Dev UI to be run in fullscreen in some cases * LP #1890573: Stop the signalling session when a container no longer exists to avoid hanging the client for too long -* LP #1886200: Fixed issues that appeared when displaying web pages on a software rendering backend -(`swrast` and `webrtc` without GPU) after upgrading the system WebView to 84.0.4147.89. +* LP #1886200: Fixed issues that appeared when displaying web pages on a software rendering backend (`swrast` and `webrtc` without GPU) after upgrading the system WebView to 84.0.4147.89. * Reduced resource consumption of the WebRTC platform by avoiding unnecessary screen refresh cycles * Fixed timing issue which resulted in locked databases in some cases on the Stream Gateway \ No newline at end of file diff --git a/reference/release-notes/1.7.1.md b/reference/release-notes/1.7.1.md index 7a32c377..8c2fd49c 100644 --- a/reference/release-notes/1.7.1.md +++ b/reference/release-notes/1.7.1.md @@ -1,17 +1,20 @@ -### Introduction +--- +orphan: true +--- +# 1.7.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.7.1 -#### New Features & Improvements +## New Features & Improvements * Switched to [LLVMpipe](https://docs.mesa3d.org/gallium/drivers/llvmpipe.html) based software rendering in favour of [swiftshader](https://swiftshader.googlesource.com/SwiftShader/) to mitigate memory corruption during rendering in the [Android WebView](https://developer.android.com/reference/android/webkit/WebView) on both ARM and x86 -#### Bug Fixes +## Bug Fixes * LP #1892149: `anbox-shell pm install` fails in the prepare hook of an addon when bootstrapping an application * LP #1889747: Coturn should not run as root * LP #1891746: Some ARM applications crash because of failing `cacheflush` syscall -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.7.1 release. \ No newline at end of file +Please see the {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.7.1 release. \ No newline at end of file diff --git a/reference/release-notes/1.7.2.md b/reference/release-notes/1.7.2.md index 66a9f252..0722ef2d 100644 --- a/reference/release-notes/1.7.2.md +++ b/reference/release-notes/1.7.2.md @@ -1,8 +1,11 @@ -### Introduction +--- +orphan: true +--- +# 1.7.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.7.2 -#### New Features & Improvements +## New Features & Improvements * Various improvements for HA support in the Anbox Stream Gateway and its [Dqlite](https://dqlite.io) integration * The Anbox Stream Gateway now exposes a `/1.0/status` endpoint to allow simple health checks @@ -10,11 +13,11 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.7.2 * The LXD charm can now use Juju storage (AWS EBS, ..) at deployment time as base for the LXD storage pool * Coturn can now be manually configured via the Anbox Stream Agent charm configuration -#### Bug Fixes +## Bug Fixes * Various fixes around interoperability of the various charms in an Anbox Cloud deployment * Updated and verified NRPE checks for all service components -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.7.2 release. \ No newline at end of file +Please see the {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.7.2 release. \ No newline at end of file diff --git a/reference/release-notes/1.7.3.md b/reference/release-notes/1.7.3.md index 3794e06b..7e33da6f 100644 --- a/reference/release-notes/1.7.3.md +++ b/reference/release-notes/1.7.3.md @@ -1,16 +1,19 @@ -### Introduction +--- +orphan: true +--- +# 1.7.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.7.3 -#### New Features & Improvements +## New Features & Improvements * Android security fixes from September 2020 (patch level `2020-09-05`, see [here](https://source.android.com/security/bulletin/2020-09-01) for more details) * WebView update to upstream release ` 85.0.4183.101` (see [here](https://chromereleases.googleblog.com/2020/09/chrome-for-android-update.html) for more details) -#### Bug Fixes +## Bug Fixes None -#### Upgrade Instructions +## Upgrade Instructions -This release does not include any charm changes. Only images are updated and will be automatically synchronised to your Anbox Cloud deployment via the Canonical image server. See [Image Management](https://discourse.ubuntu.com/t/managing-images/17758) for more details. \ No newline at end of file +This release does not include any charm changes. Only images are updated and will be automatically synchronised to your Anbox Cloud deployment via the Canonical image server. See {ref}`howto-manage-images` for more details. \ No newline at end of file diff --git a/reference/release-notes/1.7.4.md b/reference/release-notes/1.7.4.md index 56fbb98b..361c20c4 100644 --- a/reference/release-notes/1.7.4.md +++ b/reference/release-notes/1.7.4.md @@ -1,16 +1,19 @@ -### Introduction +--- +orphan: true +--- +# 1.7.4 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.7.4 -#### New Features & Improvements +## New Features & Improvements * Android security fixes from October 2020 (patch level `2020-10-05` , see [here](https://source.android.com/security/bulletin/2020-10-01) for more details) * WebView update to upstream release `86.0.4240.75` (see [here](https://chromereleases.googleblog.com/2020/10/chrome-for-android-update.html) for more details) -#### Bug Fixes +## Bug Fixes None -#### Upgrade Instructions +## Upgrade Instructions -This release does not include any charm changes. Only images are updated and will be automatically synchronised to your Anbox Cloud deployment via the Canonical image server. See [Image Management ](https://discourse.ubuntu.com/t/managing-images/17758) for more details. \ No newline at end of file +This release does not include any charm changes. Only images are updated and will be automatically synchronised to your Anbox Cloud deployment via the Canonical image server. See {ref}`howto-manage-images` for more details. \ No newline at end of file diff --git a/reference/release-notes/1.8.0.md b/reference/release-notes/1.8.0.md index 155ad0ef..9babdb5f 100644 --- a/reference/release-notes/1.8.0.md +++ b/reference/release-notes/1.8.0.md @@ -1,8 +1,11 @@ -### Introduction +--- +orphan: true +--- +# 1.8.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.0. -#### New Features & Improvements +## New Features & Improvements * Camera can now be provided with video and static images as content via the Anbox HTTP API * A new `ANBOX_EXIT_CODE` environment variable is provided to the `backup` hook of addons to provide information if Anbox terminate correctly or not @@ -20,7 +23,7 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.0. * Applications in AMS can now provide a free-form version field in their manifest to allow users to identify which application version is based on which APK version -#### Bugs +## Bugs * LP #1898180 AMS fails when related to Anbox registry due to missing certificate * LP #1901513 Don't join Dqlite cluster if gateway is not able to start @@ -53,6 +56,6 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.0. * LP #1898697 `anbox-stream-sdk. _unregisterControls` is not working correctly * LP #1894978 Sanitise prepare hook upon an addon creation -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.8.0 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.8.0 release. \ No newline at end of file diff --git a/reference/release-notes/1.8.1.md b/reference/release-notes/1.8.1.md index 09561188..a405507d 100644 --- a/reference/release-notes/1.8.1.md +++ b/reference/release-notes/1.8.1.md @@ -1,14 +1,17 @@ -### Introduction +--- +orphan: true +--- +# 1.8.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.1. -#### New Features & Improvements +## New Features & Improvements * Android security fixes from November 2020 (patch level `2020-11-05`, see [here](https://source.android.com/security/bulletin/2020-11-01) for more details) * WebView update to upstream release ` 86.0.4240.185` (see [here](https://chromereleases.googleblog.com/2020/11/chrome-for-android-update.html) for more details) * AMS now allows locking image updates to it's own minor version. For example if AMS is at 1.8 it wont pull a 1.9 image but only patch releases for 1.8. This can be configured with the `images.version_lockstep` configuration option -#### Bugs +## Bugs * LP #1903510 `nagios_context` and `nagios_servicegroups` are never used in any charm * LP #1885926 One touch point always stays when another touch event was fired @@ -25,6 +28,6 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.1. * LP #1903672 Application bootstrap fails due to malformed addon name * LP #1902650 The error message needs to be simplified when ABI is unmatched -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.8.1 release. +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.8.1 release. diff --git a/reference/release-notes/1.8.2.md b/reference/release-notes/1.8.2.md index b5d208af..90539a6d 100644 --- a/reference/release-notes/1.8.2.md +++ b/reference/release-notes/1.8.2.md @@ -1,20 +1,23 @@ -### Introduction +--- +orphan: true +--- +# 1.8.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.2. There are no charm upgrades for 1.8.2. Only new images are provided which should automatically arrive on your Anbox Cloud deployment shortly. -#### New Features & Improvements +## New Features & Improvements * Android security fixes from December 2020 (patch level `2020-12-05`, see [here](https://source.android.com/security/bulletin/2020-12-01) for more details) * WebView update to upstream release ` 87.0.4280.86` (see [here](https://chromereleases.googleblog.com/2020/12/chrome-for-android-update.html) for more details) -### Bugs +## Bugs * LP #1907464 NvEnc fails to encode when stream is in portrait mode (720x1280) * LP #1904078 Garbled image/video generated when taking a picture/recording a video when screen orientation is in portrait mode * LP #1904417 [REGRESSION] `adb screenrecord` output has incorrect orientation -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.8.2 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.8.2 release. \ No newline at end of file diff --git a/reference/release-notes/1.8.3.md b/reference/release-notes/1.8.3.md index 3f77dedb..df3fa633 100644 --- a/reference/release-notes/1.8.3.md +++ b/reference/release-notes/1.8.3.md @@ -1,18 +1,21 @@ -### Introduction +--- +orphan: true +--- +# 1.8.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.8.3. -#### New Features & Improvements +## New Features & Improvements * Android security fixes from January 2021 (patch level `2021-01-05`, see [here](https://source.android.com/security/bulletin/2021-01-01) for more details) * WebView update to upstream release `87.0.4280.141` (see [here](https://chromereleases.googleblog.com/2021/01/chrome-for-android-update.html) for more details) * Various improvements to the Coturn charm to allow proper use behind [AWS Elastic Load Balancers](https://aws.amazon.com/elasticloadbalancing/) -### Bugs +## Bugs * LP #1910583 Anbox-stream-gateway gets stuck and demands restart after some time of use * LP #1912342 Gateway reports database locked errors for various operations -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.8.3 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.8.3 release. \ No newline at end of file diff --git a/reference/release-notes/1.9.0.md b/reference/release-notes/1.9.0.md index a69853a6..c981a355 100644 --- a/reference/release-notes/1.9.0.md +++ b/reference/release-notes/1.9.0.md @@ -1,18 +1,21 @@ -### Introduction +--- +orphan: true +--- +# 1.9.0 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.0 -#### Deprecations +## Deprecations * The Android 7 (`bionic:android7:arm64` and `bionic:android7:amd64`) images are now deprecated and will no longer be available starting with Anbox Cloud 1.10 which will be released in April 2021 * The UI included in the Anbox Stream Gateway service will be dropped in Anbox Cloud 1.10 as it's being replaced with the new dashboard -#### Known Issues +## Known Issues * At times the `anbox-cloud-dashboard` charm reports a `error` as workload status due to too many units trying to use `apt` on the machine at the same time. Juju will retry the installation after some time automatically and the problem will fix itself. The issue can be identified in the output of `juju debug-log --include anbox-cloud-dashboard`. This will be improved in the upcoming 1.9.1 release * If for the initial deployment not Ubuntu Advantage token is configured via an `overlay.yaml` the status messages reported by the charms once they become idle is not set to `UA token missing`. There is no impact in terms of functionality. Applying the UA token via `juju config ua_token=` will work as usual. -#### New Features & Improvements +## New Features & Improvements * New web based dashboard to manage applications and streaming sessions in Anbox Cloud * WebView based on [upstream 88.0.4324.152 release](https://chromereleases.googleblog.com/2021/02/chrome-for-android-update_4.html) @@ -42,7 +45,7 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.0 * The Google STUN server is no longer used * Streaming sessions are now ephemeral by default and will be automatically removed when the container it belongs to terminates -### Bugs +## Bugs * LP #1868945 Android: failed to get memory consumption info * LP #1873393 Close of unknown file descriptor in `gralloc` modules causes crash @@ -92,6 +95,6 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.0 * LP #1914811 NVIDIA kernel modules are not loaded after deployment * LP #1914991 Latest gateway API changes break dashboard -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.9.0 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.9.0 release. \ No newline at end of file diff --git a/reference/release-notes/1.9.1.md b/reference/release-notes/1.9.1.md index 0aad5a35..a7dc3191 100644 --- a/reference/release-notes/1.9.1.md +++ b/reference/release-notes/1.9.1.md @@ -1,10 +1,13 @@ -### Introduction +--- +orphan: true +--- +# 1.9.1 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.1 **NOTE:** The LXD images will be released on March 5 2021. The 1.9.1 charms are already available. -#### New Features & Improvements +## New Features & Improvements * The Coturn charm is now able to figure out the public address of a manually added machine in a Juju model when deployed on AWS * The Coturn charm does now allow customising the UDP relay port range @@ -12,7 +15,7 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.1 * WebView based on [upstream 88.0.4324.181 release](https://chromereleases.googleblog.com/2021/02/chrome-for-android-update_16.html) * Android security updates for March 2021 (see [here](https://source.android.com/security/bulletin/2021-03-01) for more details) -#### Bugs +## Bugs * LP #1917578 Dashboards crashes in CI when ran on AWS because it can't reach metadata service * LP #1913565 Exposing services on private endpoint makes them not accessible @@ -37,6 +40,6 @@ The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.1 * LP #1917053 `linux-modules-extra` package should be installed as the dependency of `anbox-module-dkms` when bootstrapping LXD charm * LP #1917286 no audio output for streaming on IOS and Mac OS -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.9.1 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.9.1 release. \ No newline at end of file diff --git a/reference/release-notes/1.9.2.md b/reference/release-notes/1.9.2.md index a415c8c5..71ea00b3 100644 --- a/reference/release-notes/1.9.2.md +++ b/reference/release-notes/1.9.2.md @@ -1,14 +1,17 @@ -### Introduction +--- +orphan: true +--- +# 1.9.2 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.2. -Please see and [component versions](https://discourse.ubuntu.com/t/component-versions/21413) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New Features & Improvements +## New Features & Improvements -* Stability and reliability improvements in AMS and the Juju charms for auto scaling of the LXD cluster. See the [documentation](https://anbox-cloud.io/docs/lxd-auto-scaling) for recommendations and guidelines on how to implement auto scaling. +* Stability and reliability improvements in AMS and the Juju charms for auto scaling of the LXD cluster. See the {ref}`sec-lxd-auto-scaling` for recommendations and guidelines on how to implement auto scaling. -#### Bugs +## Bugs * LP #1910676 AMS leaks file descriptors * LP #1917862 AMS charm tries to add/remove node when AMS service is not available @@ -19,6 +22,6 @@ Please see and [component versions](https://discourse.ubuntu.com/t/component-ver * LP #1918675 Image synchronisation is not triggered in AMS when relevant config items change * LP #1918676 Image server configuration can be stale in HA AMS -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.9.2 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.9.2 release. \ No newline at end of file diff --git a/reference/release-notes/1.9.3.md b/reference/release-notes/1.9.3.md index 940a3f4b..9ec2b2c9 100644 --- a/reference/release-notes/1.9.3.md +++ b/reference/release-notes/1.9.3.md @@ -1,10 +1,13 @@ -### Introduction +--- +orphan: true +--- +# 1.9.3 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.3. -Please see and [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New Features & Improvements +## New Features & Improvements * The LXD charm can now take a `lxd-binary` resource which allows attaching and detaching custom build LXD binaries * `amc delete` has now a `--force` flag which allows deleting container without gracefully stopping them @@ -13,7 +16,7 @@ Please see and [component versions](https://anbox-cloud.io/docs/component-versio * WebView based on [upstream 89.0.4389.105 release](https://chromereleases.googleblog.com/2021/03/chrome-for-android-update_22.html) * Android security updates for April 2021 (see [here](https://source.android.com/security/bulletin/2021-04-01) for more details) -#### Bugs +## Bugs * LP #1917768 A crash occurred in the `glib` main loop thread during the streaming * LP #1918601 Metrics reported by AMS are out-of-sync @@ -37,6 +40,6 @@ Please see and [component versions](https://anbox-cloud.io/docs/component-versio * LP #1922313 `rild` service auto started when Android system fully boots up * LP #1916047 Daemon subcommand of the appliance is not hidden -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.9.3 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.9.3 release. \ No newline at end of file diff --git a/reference/release-notes/1.9.4.md b/reference/release-notes/1.9.4.md index 2bb7704f..6fcc5e9e 100644 --- a/reference/release-notes/1.9.4.md +++ b/reference/release-notes/1.9.4.md @@ -1,20 +1,23 @@ -### Introduction +--- +orphan: true +--- +# 1.9.4 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.4. -Please see and [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New Features & Improvements +## New Features & Improvements The 1.9.4 release adapts the AMS service to work with LXD newer than 4.0.5. LXD recently changed which certificate is being used on the API endpoint when running clustered. With newer LXD versions, AMS fails to setup the initial LXD node within a cluster. For subsequently added nodes, the problem does not exist. With the 1.9.4 release, AMS now correctly uses the new certificate used by LXD and allows the initial LXD cluster bootstrap to succeed. The only component updated with the 1.9.4 release is the AMS service. All other components are not changed and remain at version 1.9.3. -#### Bugs +## Bugs No bugs were fixed in this release. -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.9.4 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.9.4 release. \ No newline at end of file diff --git a/reference/release-notes/1.9.5.md b/reference/release-notes/1.9.5.md index 7b507107..06de275f 100644 --- a/reference/release-notes/1.9.5.md +++ b/reference/release-notes/1.9.5.md @@ -1,14 +1,17 @@ -### Introduction +--- +orphan: true +--- +# 1.9.5 The Anbox Cloud team is pleased to announce the release of Anbox Cloud 1.9.5 -Please see and [component versions](https://anbox-cloud.io/docs/component-versions) for a list of updated components. +Please see {ref}`ref-component-versions` for a list of updated components. -#### New Features & Improvements +## New Features & Improvements No features were added in this release. -#### Bugs +## Bugs * LP #1927676 No image is imported in AMS when deploying 1.9.x based Anbox Cloud @@ -16,6 +19,6 @@ No features were added in this release. Existing deployments based on 1.9.x are not affected by this bug. -#### Upgrade Instructions +## Upgrade Instructions -Please see the [general upgrade guide](https://anbox-cloud.io/docs/installation/upgrading-from-previous-versions) for instructions of how to update your Anbox Cloud deployment to the 1.9.5 release. \ No newline at end of file +See {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance` for instructions of how to update your Anbox Cloud deployment to the 1.9.5 release. \ No newline at end of file diff --git a/reference/release-notes/release-notes-template.md b/reference/release-notes/release-notes-template.md index 8a8e822b..143fd239 100644 --- a/reference/release-notes/release-notes-template.md +++ b/reference/release-notes/release-notes-template.md @@ -1,4 +1,7 @@ -## Introduction +--- +orphan: true +--- +# < Release version > The Anbox Cloud team is pleased to announce the release of Anbox Cloud < release-version >. diff --git a/reference/release-notes/release-notes.md b/reference/release-notes/release-notes.md index 60a06458..d131c39e 100644 --- a/reference/release-notes/release-notes.md +++ b/reference/release-notes/release-notes.md @@ -1,9 +1,12 @@ +(ref-release-notes)= +# Release notes + This page outlines the release notes of all versions of Anbox Cloud. If you're interested in getting notified for the latest Anbox Cloud releases, make sure you subscribe to notifications on the [announcements category](https://discourse.ubuntu.com/c/anbox-cloud/announcements/55) on the Anbox Cloud discourse. -For instructions on how to update your Anbox Cloud deployment to later versions, see [How to upgrade Anbox Cloud](https://discourse.ubuntu.com/t/upgrading-from-previous-versions/17750) or [How to upgrade the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/upgrade-anbox-cloud-appliance/24186). +For instructions on how to update your Anbox Cloud deployment to later versions, see {ref}`howto-upgrade-anbox-cloud` or {ref}`howto-upgrade-appliance`. ## Upcoming releases -The following dates for upcoming releases are not final and could vary depending on various factors such as availability of Android security patches. The release notes link will be updated on the day of the release. See the [release roadmap](https://discourse.ubuntu.com/t/19359) to know the targeted features for a future release. +The following dates for upcoming releases are not final and could vary depending on various factors such as availability of Android security patches. The release notes link will be updated on the day of the release. See the {ref}`ref-roadmap` to know the targeted features for a future release. | Tentative Release date | Planned release version | |----|----| @@ -16,8 +19,8 @@ The following dates for upcoming releases are not final and could vary depending | Release date | Release notes | |----|----| -| June 13 2024 | [Anbox Cloud 1.22.1](https://discourse.ubuntu.com/t/45752) | -| May 15 2024 | [Anbox Cloud 1.22.0](https://discourse.ubuntu.com/t/45074) | +| June 13 2024 | [Anbox Cloud 1.22.1](1.22.1.md) | +| May 15 2024 | [Anbox Cloud 1.22.0](1.22.0.md) | ### What's new in 1.22.x? @@ -35,448 +38,107 @@ Along with bug fixes and general improvements, Anbox Cloud 1.22.x includes: * Android security updates ## Older releases -[Details=Expand to access release notes of earlier versions] ## 2024 | Release date | Release notes | |----|----| -| January 17 2024 | [Anbox Cloud 1.20.2](https://discourse.ubuntu.com/t/41686) | -| February 14 2024 | [Anbox Cloud 1.21.0](https://discourse.ubuntu.com/t/42429) | -| March 13 2024 | [Anbox Cloud 1.21.1](https://discourse.ubuntu.com/t/43279) | -| April 18 2024 | [Anbox Cloud 1.21.2](https://discourse.ubuntu.com/t/44276) | +| January 17 2024 | [Anbox Cloud 1.20.2](1.20.2.md) | +| February 14 2024 | [Anbox Cloud 1.21.0](1.21.0.md) | +| March 13 2024 | [Anbox Cloud 1.21.1](1.21.1.md) | +| April 18 2024 | [Anbox Cloud 1.21.2](1.21.2.md) | -## 2023 +### 2023 | Release date | Release notes | |----|----| -|December 13 2023| [Anbox Cloud 1.20.1](https://discourse.ubuntu.com/t/40988) | -|November 16 2023 | [Anbox Cloud 1.20.0](https://discourse.ubuntu.com/t/40281) | -|October 11 2023|[Anbox Cloud 1.19.2](https://discourse.ubuntu.com/t/39311)| -|September 13 2023|[Anbox Cloud 1.19.1](https://discourse.ubuntu.com/t/38595)| -|August 30 2023|[Anbox Cloud 1.19.0-fix1](https://discourse.ubuntu.com/t/38250)| -|August 16 2023|[Anbox Cloud 1.19.0](https://discourse.ubuntu.com/t/37849)| -|July 12 2023|[Anbox Cloud 1.18.2](https://discourse.ubuntu.com/t/36916)| -|June 14 2023|[Anbox Cloud 1.18.1](https://discourse.ubuntu.com/t/36309)| -|May 17 2023|[Anbox Cloud 1.18.0](https://discourse.ubuntu.com/t/35812)| -|April 17 2023|[Anbox Cloud 1.17.2](https://discourse.ubuntu.com/t/35195)| -|March 16 2023|[Anbox Cloud 1.17.1](https://discourse.ubuntu.com/t/34573)| -|February 15 2023|[Anbox Cloud 1.17.0](https://discourse.ubuntu.com/t/33927)| -|January 24 2023|[Anbox Cloud 1.16.4](https://discourse.ubuntu.com/t/33437)| -|January 17 2023|[Anbox Cloud 1.16.3](https://discourse.ubuntu.com/t/33261)| -|January 12 2023|[Anbox Cloud 1.16.2](https://discourse.ubuntu.com/t/33161)| - -## 2022 +|December 13 2023| [Anbox Cloud 1.20.1](1.20.1.md) | +|November 16 2023 | [Anbox Cloud 1.20.0](1.20.0.md) | +|October 11 2023|[Anbox Cloud 1.19.2](1.19.2.md)| +|September 13 2023|[Anbox Cloud 1.19.1](1.19.1.md)| +|August 30 2023|[Anbox Cloud 1.19.0-fix1](1.19.0-fix1.md)| +|August 16 2023|[Anbox Cloud 1.19.0](1.19.0.md)| +|July 12 2023|[Anbox Cloud 1.18.2](1.18.2.md)| +|June 14 2023|[Anbox Cloud 1.18.1](1.18.1.md)| +|May 17 2023|[Anbox Cloud 1.18.0](1.18.0.md)| +|April 17 2023|[Anbox Cloud 1.17.2](1.17.2.md)| +|March 16 2023|[Anbox Cloud 1.17.1](1.17.1.md)| +|February 15 2023|[Anbox Cloud 1.17.0](1.17.0.md)| +|January 24 2023|[Anbox Cloud 1.16.4](1.16.4.md)| +|January 17 2023|[Anbox Cloud 1.16.3](1.16.3.md)| +|January 12 2023|[Anbox Cloud 1.16.2](1.16.2.md)| + +### 2022 | Release date | Release notes | |----|----| -|December 14 2022|[Anbox Cloud 1.16.1](https://discourse.ubuntu.com/t/32733)| -|November 16 2022|[Anbox Cloud 1.16.0](https://discourse.ubuntu.com/t/32264)| -|October 20 2022|[Anbox Cloud 1.15.3](https://discourse.ubuntu.com/t/31616)| -|October 12 2022|[Anbox Cloud 1.15.2](https://discourse.ubuntu.com/t/31322)| -|September 14 2022|[Anbox Cloud 1.15.1](https://discourse.ubuntu.com/t/30585)| -|August 24 2022|[Anbox Cloud 1.15.0](https://discourse.ubuntu.com/t/30196)| -|July 18 2022|[Anbox Cloud 1.14.2](https://discourse.ubuntu.com/t/29553)| -|June 16 2022|[Anbox Cloud 1.14.1](https://discourse.ubuntu.com/t/28952)| -|May 23 2022|[Anbox Cloud 1.14.0](https://discourse.ubuntu.com/t/28557)| -|April 13 2022|[Anbox Cloud 1.13.2](https://discourse.ubuntu.com/t/27701)| -|March 21 2022|[Anbox Cloud 1.13.1](https://discourse.ubuntu.com/t/27254)| -|February 24 2022|[Anbox Cloud 1.13.0](https://discourse.ubuntu.com/t/26857)| -|February 15 2022|[Anbox Cloud 1.11.5](https://discourse.ubuntu.com/t/26739)| -|January 28 2022|[Anbox Cloud 1.12.5](https://discourse.ubuntu.com/t/26380)| -|January 21 2022|[Anbox Cloud 1.12.4](https://discourse.ubuntu.com/t/26263)| -|January 20 2022|[Anbox Cloud 1.12.3](https://discourse.ubuntu.com/t/26252)| - -## 2021 +|December 14 2022|[Anbox Cloud 1.16.1](1.16.1.md)| +|November 16 2022|[Anbox Cloud 1.16.0](1.16.0.md)| +|October 20 2022|[Anbox Cloud 1.15.3](1.15.3.md)| +|October 12 2022|[Anbox Cloud 1.15.2](1.15.2.md)| +|September 14 2022|[Anbox Cloud 1.15.1](1.15.1.md)| +|August 24 2022|[Anbox Cloud 1.15.0](1.15.0.md)| +|July 18 2022|[Anbox Cloud 1.14.2](1.14.2.md)| +|June 16 2022|[Anbox Cloud 1.14.1](1.14.1.md)| +|May 23 2022|[Anbox Cloud 1.14.0](1.14.0.md)| +|April 13 2022|[Anbox Cloud 1.13.2](1.13.2.md)| +|March 21 2022|[Anbox Cloud 1.13.1](1.13.1.md)| +|February 24 2022|[Anbox Cloud 1.13.0](1.13.0.md)| +|February 15 2022|[Anbox Cloud 1.11.5](1.11.5.md)| +|January 28 2022|[Anbox Cloud 1.12.5](1.12.5.md)| +|January 21 2022|[Anbox Cloud 1.12.4](1.12.4.md)| +|January 20 2022|[Anbox Cloud 1.12.3](1.12.3.md)| + +### 2021 | Release date | Release notes | |----|----| -|December 16 2021|[Anbox Cloud 1.12.2](https://discourse.ubuntu.com/t/25819)| -|November 30 2021|[Anbox Cloud 1.12.1](https://discourse.ubuntu.com/t/25542)| -|November 16 2021|[Anbox Cloud 1.12.0](https://discourse.ubuntu.com/t/25295)| -|November 1 2021|[Anbox Cloud 1.11.4](https://discourse.ubuntu.com/t/25018)| -|October 18 2021|[Anbox cloud 1.11.3](https://discourse.ubuntu.com/t/24705)| -|September 20 2021|[Anbox Cloud 1.11.2](https://discourse.ubuntu.com/t/24293)| -|August 17 2021|[Anbox Cloud 1.11.1](https://discourse.ubuntu.com/t/23772)| -|August 5 2021|[Anbox Cloud 1.11.0](https://discourse.ubuntu.com/t/23590)| -|July 14 2021|[Anbox Cloud 1.10.3](https://discourse.ubuntu.com/t/23267)| -|June 13 2021|[Anbox Cloud 1.10.2](https://discourse.ubuntu.com/t/22692)| -|May 13 2021|[Anbox Cloud 1.10.1](https://discourse.ubuntu.com/t/22280)| -|May 11 2021|[Anbox Cloud 1.9.5](https://discourse.ubuntu.com/t/22259)| -|May 6 2021|[Anbox Cloud 1.10.0](https://discourse.ubuntu.com/t/22205)| -|May 3 2021|[Anbox Cloud 1.9.4](https://discourse.ubuntu.com/t/22148)| -|April 13 2021|[Anbox Cloud 1.9.3](https://discourse.ubuntu.com/t/21795)| -|March 17 2021|[Anbox Cloud 1.9.2](https://discourse.ubuntu.com/t/21420)| -|March 4 2021|[Anbox Cloud 1.9.1](https://discourse.ubuntu.com/t/21232)| -|February 10 2021|[Anbox Cloud 1.9.0](https://discourse.ubuntu.com/t/20870)| -|January 19 2021|[Anbox Cloud 1.8.3](https://discourse.ubuntu.com/t/20435)| - -## 2020 +|December 16 2021|[Anbox Cloud 1.12.2](1.12.2.md)| +|November 30 2021|[Anbox Cloud 1.12.1](1.12.1.md)| +|November 16 2021|[Anbox Cloud 1.12.0](1.12.0.md)| +|November 1 2021|[Anbox Cloud 1.11.4](1.11.4.md)| +|October 18 2021|[Anbox cloud 1.11.3](1.11.3.md)| +|September 20 2021|[Anbox Cloud 1.11.2](1.11.2.md)| +|August 17 2021|[Anbox Cloud 1.11.1](1.11.1.md)| +|August 5 2021|[Anbox Cloud 1.11.0](1.11.0.md)| +|July 14 2021|[Anbox Cloud 1.10.3](1.10.3.md)| +|June 13 2021|[Anbox Cloud 1.10.2](1.10.2.md)| +|May 13 2021|[Anbox Cloud 1.10.1](1.10.1.md)| +|May 11 2021|[Anbox Cloud 1.9.5](1.9.5.md)| +|May 6 2021|[Anbox Cloud 1.10.0](1.10.0.md)| +|May 3 2021|[Anbox Cloud 1.9.4](1.9.4.md)| +|April 13 2021|[Anbox Cloud 1.9.3](1.9.3.md)| +|March 17 2021|[Anbox Cloud 1.9.2](1.9.2.md)| +|March 4 2021|[Anbox Cloud 1.9.1](1.9.1.md)| +|February 10 2021|[Anbox Cloud 1.9.0](1.9.0.md)| +|January 19 2021|[Anbox Cloud 1.8.3](1.8.3.md)| + +### 2020 | Release date | Release notes | |----|----| -|December 17 2020|[Anbox Cloud 1.8.2](https://discourse.ubuntu.com/t/19951)| -|November 12 2020|[Anbox Cloud 1.8.1](https://discourse.ubuntu.com/t/19319)| -|November 4 2020|[Anbox Cloud 1.8.0](https://discourse.ubuntu.com/t/19200)| -|October 15 2020|[Anbox Cloud 1.7.4](https://discourse.ubuntu.com/t/18812)| -|September 23 2020|[Anbox Cloud 1.7.3](https://discourse.ubuntu.com/t/18458)| -|September 11 2020|[Anbox Cloud 1.7.2](https://discourse.ubuntu.com/t/18265)| -|August 21 2020|[Anbox Cloud 1.7.1](https://discourse.ubuntu.com/t/17977)| - -[Details=Prior to 1.7.1] -[Details=1.7.0] - -## 1.7.0 (August 2020) - -### New features & improvements - -* Anbox Cloud is now fully integrated with [Ubuntu Advantage](https://ubuntu.com/advantage) -* TLS certificates are now managed through a common CA for all components ([Easy-RSA](https://charmhub.io/containers-easyrsa)) -* GPS position updates can now be provided via a new HTTP API endpoint Anbox exposes within the container or via the streaming SDK -* Removed [KSM](https://www.kernel.org/doc/html/latest/admin-guide/mm/ksm.html) support -* Allow streams started via the stream gateway UI to use 1080p as display resolution -* Deprecated the Anbox Cloud Doctor in favour of [Juju crashdump](https://github.com/juju/juju-crashdump) - -### Bug fixes - -* LP #1890573: Always delete the base container even when an application failed to be bootstrapped -* LP #1847226 Fixed a bug that prevented the Dev UI to be run in fullscreen in some cases -* LP #1890573: Stop the signalling session when a container no longer exists to avoid hanging the client for too long -* LP #1886200: Fixed issues that appeared when displaying web pages on a software rendering backend -(`swrast` and `webrtc` without GPU) after upgrading the system WebView to 84.0.4147.89. -* Reduced resource consumption of the WebRTC platform by avoiding unnecessary screen refresh cycles -* Fixed timing issue which resulted in locked databases in some cases on the Stream Gateway - -[/Details] - -[Details=1.6.3] - -## 1.6.3 (July 2020) - -### Bug fixes - -* LP #1885726: Fix the mouse and touch displacement issue for Anbox Stream Gateway UI - -[/Details] - -[Details=1.6.1] - -## 1.6.1 (June 2020) - -### Bug fixes - -* LP #1885257: Fix high CPU usage for Anbox daemon -* LP #1885972: Fix watchdog, services and video encoder settings out of sync when updating an application - -[/Details] - -[Details=1.6.2] - -## 1.6.2 (June 2020) - -### New features & improvements - -* Applications without an APK can now specify a boot activity in their application manifest - -### Bug fixes - -* LP #1885107: Automatic application updates were missing configured resources, watchdog or service information -* LP #1885257: `anboxd` was using 100% of a single CPU core due to a spinning loop - -[/Details] - -[Details=1.6.0] - -## 1.6.0 (June 2020) - -### New features & improvements - -* Watchdog can now be disabled via the application manifest or configured to allow additional packages to provide a foreground activity -* Service endpoints can now be defined in the application manifest -* Full HA support for the streaming stack -* Rejoining a streaming session when the initial client left is now possible and can be configured via the stream gateway API when a new session is created -* GPU acceleration support for Tensorflow Lite via the [GPU delegate](https://www.tensorflow.org/lite/performance/gpu) on supported GPUs (requires OpenGL ES >= 3.1) -* GPS support in the Anbox Platform SDK -* GPS position can be statically configured before the Android system boots -* Application resources (CPU, memory, disk, GPUs) can now be declared in the application manifest as an alternative to predefined instance types -* Updated Android WebView to 83.0.4103.96 -* Latest security updates for Android 10 (patch level [2020-06-05](https://source.android.com/security/bulletin/2020-06-01)) -* Manual mode for the Anbox Application Registry (AAR) which allows pushing and pulling applications via the REST API or the `amc` command line client to or from the registry -* Improved audio latency for the streaming protocol implementation -* Various fixes for improved Android system stability -* Increased [Android CTS](https://source.android.com/compatibility/cts) test coverage -* The Anbox Streaming SDK now comes with an Android example to demonstrate how to utilise streaming within an Android application. - -[/Details] - -[Details=1.5.2] - -## 1.5.2 (June 2020) - -### New features & improvements - -* Fix infinite loading screen issue when streaming from Anbox Stream Gateway UI -* Fix SDK documentation for Anbox Stream Gateway and all API routes are prefixed with "/1.0" -* Reconfigure Anbox Stream Gateway upon charm upgrade - -[/Details] - -[Details=1.5.1] - -## 1.5.1 (May 2020) - -### New features & improvements - -* Fix timeout issue when adding or removing LXD nodes from the cluster in AMS -* Containers are now gracefully terminated to ensure the backup hook is executed -* Support to start a container with one specific application version from Anbox Stream Gateway UI -* Support numpad and mouse wheel input for the WebRTC based Streaming Stack -* Collecting basic statistics (FPS, RTT and bandwidth) while streaming and display them in Anbox Stream Gateway UI -* Stream Gateway will not directly be exposed to the public network but only accessible via a reverse proxy -* Dropped the monitoring stack from the default Juju bundle. It is now available via an overlay - -[/Details] - -[Details=1.5] - -## 1.5 (April 2020) - -### New features & improvements - -* Support for Android 10 including latest security updates -* Updated software rendering to work on Android 10 -* Applications can now have encoder requirements (e.g. whether or not they require a GPU or are fine on a CPU encoder) and are scheduled accordingly -* Use [Dqlite](https://dqlite.io/) in the Stream Gateway for High Availability -* HTTP/HTTPS proxy support in AMS -* Highly Availability support for Anbox Stream Gateway via [Dqlite](https://dqlite.io/) -* Charms now properly work with DNS names when adding machines -* Updated Android WebView to [80.0.3987.132](https://chromereleases.googleblog.com/2020/03/stable-channel-update-for-desktop.html) -* Preliminary support for Ubuntu 20.04 -* Software rendering and video encoding support for the streaming stack -* GPUs are now identified by their PCI address in order for a correct mapping inside containers - -### Deprecations - -* Android 7 images are now deprecated and will be dropped with the next release of Anbox Cloud - -[/Details] - -[Details=1.4] - -## 1.4 (March 2020) - -### New features & improvements - -* Support for Android 10 including latest security updates -* Inclusion of an alpha version of the WebRTC based Streaming Stack -* Updated and improve OpenGL/EGL layer to provide better performance and API support up to OpenGL ES 3.2 and EGL 1.4 -* Nested Android container is now using a nested user namespace with its own user id range to further isolate the Android system from the host system. -* Support for [explicit graphics synchronisation](https://source.android.com/devices/graphics/sync) -* Automatic GPU detection on deployment and at runtime -* Default LXD version changed to 3.21 for shiftfs and extended GPU support -* Container life-cycle events are now reported via `amc monitor` and the corresponding REST API -* Support for VNC was removed as [scrcpy](https://github.com/Genymobile/scrcpy) offers a good alternative - -[/Details] - -[Details=1.3.3] - -## 1.3.3 (January 2020) - -### New features & improvements - -* Generating thumbnails within `libstagefright` in the Android 7 images is now working reliable where it was generating single coloured images at times before. -* Error messages are now presented via the AMS REST API for application versions. -* The configuration of a container was created with (platform, boot package, ...) was added to the container REST API object which makes it visible with `$ amc show ` for later inspection -* Life-cycle events are now returned from the monitor endpoint the AMS REST API provides -* Download of addons is now retried up to three times during the container bootstrap to workaround busy network environments -* The addon prepare hook is now correctly executed while the container is running and before the bootstrap process finishes - -[/Details] - -[Details=1.3.2] - -## 1.3.2 (October 2019) - -### New features & improvements - -* Increased maximum allowed startup time for containers to 15 minutes -* Containers can now started with additional disk space added -* Nodes can be marked as unschedulable to allow rebooting them for maintenance -* `amc` supports deleting containers on a specific node (e.g. `$ amc delete --node=lxd0 --all`) -* The default deployment configuration now allows deploying AMS and LXD on the same machine -* Integrated Android security fixes for September and October 2019. See the -[Android Security Bulletins](https://source.android.com/security/bulletin) for more information. -* Added `prepare` hook to allow customising Android while it's running as part of the bootstrap process -* Updated LXD charm to install latest NVIDIA CUDA drivers - -[/Details] - -[Details=1.3.1] - -## 1.3.1 (September 2019) - -### New features & improvements - -* Allow underlying image of an application to be changed -* Support for applications without an APK -* An Anbox platform can now specify the display refresh rate -* Integrated Android security fixes for August 2019. See the [Android Security Bulletins](https://source.android.com/security/bulletin) for more information. - -### Bug fixes - -* Refresh the LXD snap on demand when the configuration is changed -* Don't use embedded etcd when a real etcd is available -* Correctly determine the maximum OpenGL ES version the host GL driver supports -* Support for gamepad devices in Anbox and the platform SDK - -[/Details] - -[Details=1.3.0] - -## 1.3.0 (August 2019) - -### New features & improvements - -* Images are now only distributed via the official image server and no longer available for download -* The application registry received a dedicated CLI command to manage trusted clients -* A dedicated charm now takes care of deploying the Anbox Application Registry -* The disk space available to a container was reduced from 5GB to 3GB for all instance types -* Android ANR and tombstone crash logs are now pulled from a container when it fails at runtime or on startup -* Gamepad support was added to Anbox and the Platform SDK -* Sensor support was added to Anbox and the Platform SDK -* AMS now supports marking a single image as the default one which will be used if no other is specified for raw container launches or applications -* Initial support for event monitoring of the AMS service via `amc monitor` and the REST API -* The `swrast` platform is now part of the default image and doesn't need to be installed via an addon -* The `binder` and `ashmem` kernel modules are now supported on the HWE 5.0 kernel coming with Ubuntu 18.04.3 -* Services a container provides can now be named to help identifying them -* The Android container is now further secured with a more narrow [`seccomp`](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt) profile than the outer Anbox container. -* Addons can now declare that they add support for specific Android ABIs not supported by the hardware via software based binary translation -* Integrated Android security fixes until July 2019. See the [Android Security Bulletins](https://source.android.com/security/bulletin) for more information. - -[/Details] - -[Details=1.2.1] - -## 1.2.1 (April 2019) - -### Bug fixes - -* Telegraf was restarted every five minutes which caused metrics from Anbox being lost. -* Android framework crashed in [`WifiManager.getWifiState()`](https://developer.android.com/reference/android/net/wifi/WifiManager.html#getWifiState()) -* Application updates failed due to limited cluster capacity. Base containers are now queued up and processed in order as soon as capacity is available. -* AMS was not correctly finishing a container timeout on launch when restarted. On restart AMS now resumes the timeout. -* Base containers are now correctly marked as stopped during the bootstrap process when the related LXD container is also stopped. -* Fixed unhandled timeouts in the LXD API client implementation causing API calls to stall forever. -* Added Android security fixes from April 2019. See the [Android Security Bulletins](https://source.android.com/security/bulletin) for more information. -* Installing applications with an architecture not supported by the LXD cluster caused the installation process to stall. AMS now checks on APK upload if the APK can be executed by the available machines in the LXD cluster. The installation process was updated to not stall on unsupported APKs. -* The Android WebView crashed in specific scenarios with SIGBUS on ARM64. This was caused by unaligned memory access in the OpenGL translation layer inside Anbox. - -[/Details] - -[Details=1.2.0] - -## 1.2.0 (April 2019) - -### New features & improvements - -* Full support for an [Application Registry](installation-registry.md) -* Updated Android 7.x with all [security patches](https://source.android.com/security/bulletin) as of Mar 5 2019 -* Support for Intel and AMD GPUs -* If configured, images will now be automatically pulled from a Canonical provided image server which will automatically bring updates once published. -* Various performance and stability improvements -* Dynamic management of [KSM](https://www.kernel.org/doc/html/latest/admin-guide/mm/ksm.html) -* Dedicated tool to backup and restore user data of Android applications -* Extended timeouts for addon hook execution -* Tab completion (bash only) for the `amc` command -* Improve startup time for the Android container -* The `amc` command now has `shell` and `exec` subcommands to allow easy access of containers -* Applications can now be tagged -* Filtering of containers and applications via the `amc` command -* `amc wait` allows to wait for a status change of a container or application object -* Reworked APK validator for application packages -* The Android container now uses dnsmasq, as provided by LXD on the host, as DNS server -* Various improvements on the Anbox Cloud charms - -[/Details] - -[Details=1.1.1] - -## 1.1.1 (February 2019) - -### Bug fixes - -* Anbox was taking an incorrect display size from platform plugins and failed to initialise EGL rendering context. -* The Anbox container now always dumps system log files when an error occurred. - -[/Details] - -[Details=1.1.0] - -## 1.1.0 (January 2019) - -### New features & improvements - -* The Anbox container is now based on Ubuntu 18.04 -* Experimental support for an application registry which serves as a central repository of applications for multiple Anbox Cloud deployments -* Updated Android 7.x with all [security patches](https://source.android.com/security/bulletin) as of Jan 5 2019 -* Added GPU support to allow hardware accelerated rendering and video encoding/decoding -* Various improvements to container startup time and overall performance -* Improved AMS SDK (Go) -* Support for “raw” containers (containers without installed applications) -* The container scheduler now accounts for container disk requirements -* AMS exposes additional metrics (containers per app, ...) -* Anbox Platform SDK ABI version is marked as stable -* Containers logs can be retrieved via the REST API and command line tools -* Extended instance types (a6.3, a8.3, a10.3) -* Binder support is now based on the new binderfs coming with Linux 5.0 -* AMS can now run on Arm64 machines -* Example platform plugin with software rendering and VNC support - -### Known issues - -None - -[/Details] - -[Details=1.0.1] - -## 1.0.1 (December 2018) - -### Bug fixes - -* Applications are not freezing anymore when using OpenGL ES >= 2.x extensively -* AArch32 support is now properly detected on AArch64 only machines - -[/Details] - -[Details=1.0.0] - -## 1.0.0 (November 2018) - -### New features & improvements - -* First official stable release of the Anbox Cloud stack -* Simple deployment via Juju in a single command on any cloud (public, private or bare metal) -* Dedicated management service for container orchestration, managing the entire life cycle of Android applications in Anbox Cloud -* Rich REST API to talk to the management service -* Automatic container scheduling and cluster resource management -* Optimised containers for performance, scalability and high density -* Based on Android 7.1.2 -* Platform SDK to allow development of custom platform plugins to integrate with existing or new streaming solutions -* Golang SDK to allow easy use of the management service REST API -* Support for addons to extend the content of the container images -* Support for hooks inside the container images (e.g. restore/backup of user data) -* Rich online documentation -* Metrics collection support via Telegraf, Prometheus and Grafana -* High availability support for the management service -* Support for x86 and Arm64 -* Enabled for binary translation of AArch32 on AArch64 only systems -* OpenGL ES 3.x support - -### Bug fixes - -None - -### Known issues - -* A few applications freeze after some time and stop rendering. A reason is not known yet and the issue is being investigated. - -[/Details] -[/Details] -[/Details] +|December 17 2020|[Anbox Cloud 1.8.2](1.8.2.md)| +|November 12 2020|[Anbox Cloud 1.8.1](1.8.1.md)| +|November 4 2020|[Anbox Cloud 1.8.0](1.8.0.md)| +|October 15 2020|[Anbox Cloud 1.7.4](1.7.4.md)| +|September 23 2020|[Anbox Cloud 1.7.3](1.7.3.md)| +|September 11 2020|[Anbox Cloud 1.7.2](1.7.2.md)| +|August 21 2020|[Anbox Cloud 1.7.1](1.7.1.md)| +|August 2020|[Anbox Cloud 1.7.0](1.7.0.md)| +|July 2020|[Anbox Cloud 1.6.3](1.6.3.md)| +|June 2020|[Anbox Cloud 1.6.2](1.6.2.md)| +|June 2020|[Anbox Cloud 1.6.1](1.6.1.md)| +|June 2020|[Anbox Cloud 1.6.0](1.6.0.md)| +|June 2020|[Anbox Cloud 1.5.2](1.5.2.md)| +|May 2020|[Anbox Cloud 1.5.1](1.5.1.md)| +|April 2020|[Anbox Cloud 1.5.0](1.5.0.md)| +|March 2020|[Anbox Cloud 1.4.0](1.4.0.md)| +|January 2020|[Anbox Cloud 1.3.3](1.3.3.md)| + +### 2019 +|October 2019|[Anbox Cloud 1.3.2](1.3.2.md)| +|September 2019|[Anbox Cloud 1.3.1](1.3.1.md)| +|August 2019|[Anbox Cloud 1.3.0](1.3.0.md)| +|April 2019|[Anbox Cloud 1.2.1](1.2.1.md)| +|April 2019|[Anbox Cloud 1.2.0](1.2.0.md)| +|February 2019|[Anbox Cloud 1.1.1](1.1.1.md)| +|January 2019|[Anbox Cloud 1.1.0](1.1.0.md)| + +### 2018 +|December 2018|[Anbox Cloud 1.0.1](1.0.1.md)| +|November 2018|[Anbox Cloud 1.0.0](1.0.0.md)| diff --git a/reference/releases-versions.md b/reference/releases-versions.md deleted file mode 100644 index ace11cb4..00000000 --- a/reference/releases-versions.md +++ /dev/null @@ -1,6 +0,0 @@ -This section provides information on Anbox Cloud releases, product roadmap, supported versions and the component versions for each release. - -* [Release roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359) -* [Release notes](https://discourse.ubuntu.com/t/release-notes/17842) -* [Supported versions](https://discourse.ubuntu.com/t/supported-versions/21046) -* [Component versions](https://discourse.ubuntu.com/t/component-versions/21413) diff --git a/reference/requirements.md b/reference/requirements.md index 1a068b60..5c68b1ce 100644 --- a/reference/requirements.md +++ b/reference/requirements.md @@ -1,3 +1,6 @@ +(ref-requirements)= +# Requirements + To run Anbox Cloud, you must fulfil a few minimum requirements, which differ depending on the kind of deployment you choose. This topic provides information about the following requirements: @@ -6,7 +9,7 @@ This topic provides information about the following requirements: * The requirements for the Anbox Cloud Appliance variant. * The requirements for Anbox Cloud variant. -See [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1) for an explanation of the differences between both variants. +See {ref}`sec-variants` for an explanation of the differences between both variants. ## General requirements @@ -31,11 +34,11 @@ The Anbox Cloud Appliance has the following minimum hardware requirements: * 40 GB of disk space for the OS * At least 100GB block volume to host instance storage -The above defines a minimum of what is necessary to run the Anbox Cloud Appliance. As Anbox Cloud is dependent on available resources to launch its Android containers, the available resources dictate the maximum number of possible Android containers. See [About capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) for an explanation on how to plan for a specific capacity on your appliance. +The above defines a minimum of what is necessary to run the Anbox Cloud Appliance. As Anbox Cloud is dependent on available resources to launch its Android containers, the available resources dictate the maximum number of possible Android containers. See {ref}`exp-capacity-planning` for an explanation on how to plan for a specific capacity on your appliance. On public clouds, it is always recommended to allocate an additional storage volume for instance storage. If no additional storage volume is available, the appliance creates an on-disk image and uses it for instance storage. This is sufficient for very simple cases but does not provide optimal performance and will slow down operations and instance startup time. -For external access to the Anbox Cloud Appliance, you must expose a couple of network ports on the machine where the appliance is running. See [Network ports](https://discourse.ubuntu.com/t/network-ports/33650#anbox-cloud-appliance-2) for the list of ports that must be exposed. How to allow incoming traffic on the listed ports differs depending on the cloud used. See the documentation of the cloud for further information on how to change the firewall. +For external access to the Anbox Cloud Appliance, you must expose a couple of network ports on the machine where the appliance is running. See {ref}`ref-network-ports` for the list of ports that must be exposed. How to allow incoming traffic on the listed ports differs depending on the cloud used. See the documentation of the cloud for further information on how to change the firewall. ### Ubuntu version @@ -63,9 +66,9 @@ Anbox Cloud supports the following Ubuntu versions: For new deployments, Ubuntu 22.04 (jammy) is preferred. -[note type="information" status="Note"] +```{note} The HAProxy load balancer currently has no support for Ubuntu 22.04. Therefore, the Juju bundle uses Ubuntu 20.04 for the machine that runs the load balancer. -[/note] +``` ### LXD version @@ -73,6 +76,7 @@ Anbox Cloud currently supports the following LXD versions: * >= 4.0 +(sec-juju-version-requirements)= ### Juju version The regular Anbox Cloud variant requires [Juju 2.9 or later](https://juju.is/) to be installed to manage the different components and their dependencies. You can install Juju with the following command: @@ -87,7 +91,8 @@ To switch to the 2.9 series, use the following command: See the [Juju documentation](https://juju.is/docs/installing) for more information. -### Minimum hardware +(sec-minimum-hardware-requirements)= +### Minimum hardware requirements While you can run Anbox Cloud on a single machine, we strongly recommend using several machines for a production environment. @@ -95,7 +100,7 @@ To run a full Anbox Cloud deployment including the streaming stack, we recommend | ID | Architecture | CPU cores | RAM | Disk | GPUs | FUNCTION | |----|----------------|-----------|------|------------|------|------------| -| - | amd64 or arm64 | 4 | 4GB | 50GB SSD | no | Hosts the [Juju controller](https://discourse.juju.is/t/controllers/1111) | +| - | amd64 or arm64 | 4 | 4GB | 50GB SSD | no | Hosts the [Juju controller](https://juju.is/docs/juju/controller) | | 0 | amd64 or arm64 | 2 | 2GB | 100GB SSD | no | Hosts the load balancer | | 1 | amd64 or arm64 | 4 | 8GB | 100GB SSD | no | Hosts the streaming stack control plane | | 2 | amd64 or arm64 | 4 | 8GB | 100GB SSD | no | Hosts the management layer of Anbox Cloud (for example, AMS) | @@ -105,7 +110,7 @@ To run the core version of Anbox Cloud without the streaming stack, we recommend | ID | Architecture | CPU cores | RAM | Disk | GPUs | FUNCTION | |----|----------------|-----------|------|------------|------|------------| -| - | amd64 or arm64 | 4 | 4GB | 50GB SSD | no | Hosts the [Juju controller](https://discourse.juju.is/t/controllers/1111) | +| - | amd64 or arm64 | 4 | 4GB | 50GB SSD | no | Hosts the [Juju controller](https://juju.is/docs/juju/controller) | | 0 | amd64 or arm64 | 4 | 8GB | 100GB SSD | no | Hosts the management layer of Anbox Cloud (for example, AMS) | | 1 | amd64 or arm64 | 8 | 16GB | 200GB NVMe | optional | LXD worker node that hosts the actual containers or virtual machines | @@ -115,11 +120,11 @@ Some additional information: - You can mix architectures for the different machines. However, if you have several LXD nodes, all of them must have the same architecture. - The specified number of cores and RAM is only the minimum required to run Anbox Cloud at a sensible performance. - More CPU cores and more RAM on the machine hosting LXD will allow to run a higher number of instances. See [About capacity planning](https://discourse.ubuntu.com/t/about-capacity-planning/28717) for an introduction of how many resources are necessary to host a specific number of instances. -- If you require GPU support, see [Supported rendering resources](https://discourse.ubuntu.com/t/37322) for a list of supported GPUs. + More CPU cores and more RAM on the machine hosting LXD will allow to run a higher number of instances. See {ref}`exp-capacity-planning` for an introduction of how many resources are necessary to host a specific number of instances. +- If you require GPU support, see {ref}`ref-rendering-resources` for a list of supported GPUs. Applications not maintained by Anbox Cloud may have different hardware recommendations: - **etcd**: [Hardware recommendations](https://etcd.io/docs/v3.5/op-guide/hardware/) - **HAProxy** (load balancer for the Stream Gateway and the dashboard): [Installation](https://www.haproxy.com/documentation/hapee/latest/getting-started/hardware/) -Please note that these are just baselines and should be adapted to your workload. No matter the application, [monitoring and tuning the performance](https://discourse.ubuntu.com/t/about-performance/29416) is always important. +Please note that these are just baselines and should be adapted to your workload. No matter the application, monitoring and tuning the performance is always important. See {ref}`exp-performance` for more information. diff --git a/reference/roadmap.md b/reference/roadmap.md index b1c0b0da..ea191834 100644 --- a/reference/roadmap.md +++ b/reference/roadmap.md @@ -1,3 +1,6 @@ +(ref-roadmap)= +# Roadmap + In order to plan for new updates of the Anbox Cloud software stack, this page gives you insight into the general release cycle and planned features for the next versions of Anbox Cloud. However, the roadmap dates are not final and can change depending on various factors such as availability of the Android security patches. ## Release Cycle diff --git a/reference/sdks.md b/reference/sdks.md index cc4f8dad..0d178535 100644 --- a/reference/sdks.md +++ b/reference/sdks.md @@ -1,9 +1,13 @@ +(ref-sdks)= +# Anbox Cloud SDKs + Anbox Cloud provides a series of Software Development Kits (SDKs) to facilitate integrating and extending Anbox Cloud for different use cases: - Anbox Platform SDK - AMS SDK - Anbox Streaming SDK +(sec-platform-sdk)= ## Anbox Platform SDK The Anbox Platform SDK provides support for developing custom platform plugins, which allows cloud providers to integrate Anbox with their existing infrastructure. The SDK provides several integration points for things like rendering, audio or input processing. @@ -27,6 +31,7 @@ The Anbox Platform SDK provides a collection of example platform plugins to help * `minimal` - A platform plugin that provides a sample implementation of a minimal platform plugin to demonstrate the general plugin layout. * `audio_streaming` - A platform plugin that provides a more advanced example of how a platform plugin can process audio and input data. +(sec-ams-sdk)= ## AMS SDK The AMS SDK offers a set of [Go](https://golang.org/) packages and utilities for any external [Go](https://golang.org/) code to be able to connect to the AMS service through the exposed REST API. @@ -47,8 +52,9 @@ The AMS SDK comes with a set of examples demonstrating the capabilities of the S ### Authentication setup -Clients must authenticate to AMS before communicating with it. For more information, see [How to control AMS remotely](https://discourse.ubuntu.com/t/managing-ams-access/17774) and the [AMS SDK documentation](https://github.com/canonical/ams-sdk) on GitHub. +Clients must authenticate to AMS before communicating with it. For more information, see {ref}`howto-access-ams-remote` and the [AMS SDK documentation](https://github.com/canonical/ams-sdk) on GitHub. +(sec-streaming-sdk)= ## Anbox Cloud Streaming SDK The Anbox Cloud streaming SDK allows the development of custom streaming clients using JavaScript. This SDK handles all aspects of streaming, from the WebRTC protocol to handling controls, game pads, speakers and screen resolutions. @@ -80,7 +86,7 @@ Having these two components makes it easier to plug your own software in the SDK ### Download and installation -To use the Anbox Cloud streaming SDK, you must have [deployed the Anbox Streaming Stack](https://discourse.ubuntu.com/t/installation-quickstart/17744). +To use the Anbox Cloud streaming SDK, you must have deployed the Anbox Streaming Stack. See {ref}`howto-deploy-anbox-juju` for more information. You can download the Anbox Cloud streaming SDK via Git from GitHub: diff --git a/reference/supported-codecs.md b/reference/supported-codecs.md index cfb383b3..f2ac676a 100644 --- a/reference/supported-codecs.md +++ b/reference/supported-codecs.md @@ -1,3 +1,6 @@ +(ref-codecs)= +# Supported video codecs + Anbox Cloud combines both software and hardware video encoding in order to utilise available resources in the best possible way. Hardware video encoders usually have limited capacity of how many simultaneous video streams they can encode for low latency scenarios. For example, the NVIDIA T4 can encode 37 video streams at 720p and 30 frames per second (see "[Turing H.264 Video Encoding Speed and Quality](https://devblogs.nvidia.com/turing-h264-video-encoding-speed-and-quality/)" for more details). Depending on the CPU platform used, additional compute capacity might be available to support additional sessions via software encoding. Not all codecs are supported by one or more of the supported GPU models, neither are they performing suitably for low latency. Hence, the list of supported video codecs is limited. @@ -10,4 +13,4 @@ The supported video codecs are: Anbox Cloud currently supports the Opus audio codec. -Availability of additional codecs depends on them being supported by the GPU vendors in their hardware encoding solutions or if a viable software encoding solution exists. See [Release roadmap](https://discourse.ubuntu.com/t/19359) for future versions of Anbox Cloud and planned features. +Availability of additional codecs depends on them being supported by the GPU vendors in their hardware encoding solutions or if a viable software encoding solution exists. See {ref}`ref-roadmap` for future versions of Anbox Cloud and planned features. diff --git a/reference/supported-rendering-resources.md b/reference/supported-rendering-resources.md index 61ecec76..916aa1ec 100644 --- a/reference/supported-rendering-resources.md +++ b/reference/supported-rendering-resources.md @@ -1,7 +1,13 @@ +(ref-rendering-resources)= +# Supported rendering resources + This guide lists various supported GPU vendors, drivers, platforms, APIs and discuss the rendering pipelines used for different GPUs. -[note type="information" status="Important"]Currently Anbox Cloud does not support GPU for virtual machines.[/note] +```{important} +Currently Anbox Cloud does not support GPU for virtual machines. +``` +(sec-supported-gpus)= ## Supported GPU vendors and GPU models Being a cloud solution, Anbox Cloud is optimised for GPUs that are designed for a data centre. We currently support the following GPU vendors: @@ -22,7 +28,7 @@ Concrete support for the individual GPU depends on the platform being using for For GPUs on which Anbox Cloud doesn't support hardware video encoding, a software-based video encoding fallback is available. -Anbox Cloud is extensively tested using NVIDIA GPUs and occasionally, on Intel and AMD GPUs. However, if you want to use a different GPU vendor, you can customise and configure Anbox Cloud for the GPU vendor of your choice using the [Anbox Platform SDK](https://discourse.ubuntu.com/t/17844). +Anbox Cloud is extensively tested using NVIDIA GPUs and occasionally, on Intel and AMD GPUs. However, if you want to use a different GPU vendor, you can customise and configure Anbox Cloud for the GPU vendor of your choice using the Anbox Platform SDK. See {ref}`sec-platform-sdk` for more information. ## Supported GPU drivers @@ -30,8 +36,9 @@ For NVIDIA GPUs, Anbox Cloud uses the [Enterprise Ready Driver (ERD) from NVIDIA For AMD GPUs, Anbox Cloud uses the [Mesa radv](https://docs.mesa3d.org/drivers/radv.html) driver and for Intel GPUs, the [Mesa anv](https://docs.mesa3d.org/drivers/anv.html) driver. -See [Component versions](https://discourse.ubuntu.com/t/21413) to refer to the actual version supported for any particular Anbox Cloud release. +See {ref}`ref-component-versions` to refer to the actual version supported for any particular Anbox Cloud release. +(sec-supported-platforms)= ## Supported platforms Anbox Cloud can make use of different [platforms](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-platform-sdk/) to customise its behaviour and currently supports 3 platforms. @@ -65,7 +72,7 @@ The following OpenGL ES extensions are known to be unsupported by all used GPU d * [`GL_EXT_shader_framebuffer_fetch`](https://registry.khronos.org/OpenGL/extensions/EXT/EXT_shader_framebuffer_fetch.txt) * [`GL_EXT_shader_framebuffer_fetch_non_coherent`](https://registry.khronos.org/OpenGL/extensions/EXT/EXT_shader_framebuffer_fetch.txt) -## Related information +## Related topics -* [Rendering architecture](https://discourse.ubuntu.com/t/rendering-architecture/35129) -* [Configuring the Anbox Cloud platforms](https://discourse.ubuntu.com/t/anbox-platforms/18733) +* {ref}`exp-rendering-architecture` +* {ref}`exp-platforms` diff --git a/reference/supported-versions.md b/reference/supported-versions.md index 1491a1ba..d4062765 100644 --- a/reference/supported-versions.md +++ b/reference/supported-versions.md @@ -1,3 +1,6 @@ +(ref-supported-versions)= +# Supported versions + Anbox Cloud currently officially supports only the most recent release. Older releases are only supported for a short time after a new minor release was published. To ensure you receive latest security updates and bug fixes you should upgrade to a new release of Anbox Cloud shortly after it was released. @@ -5,7 +8,7 @@ To ensure you receive latest security updates and bug fixes you should upgrade t Current release: **1.22** Next release: **1.23** (scheduled for August 2024) -See the [Anbox Cloud Roadmap](https://discourse.ubuntu.com/t/release-roadmap/19359) for details on the exact schedule of upcoming Anbox Cloud versions. +See the {ref}`ref-roadmap` for details on the exact schedule of upcoming Anbox Cloud versions. ## Professional support diff --git a/reference/webrtc-streamer.md b/reference/webrtc-streamer.md index 25b0f645..1aece6ed 100644 --- a/reference/webrtc-streamer.md +++ b/reference/webrtc-streamer.md @@ -1,6 +1,9 @@ +(ref-webrtc)= +# WebRTC streamer + Usually you wouldn't need to adjust the default WebRTC streamer configuration because it is optimised to provide a good balance between low latency and high quality. However, you can still fine-tune it to provide better results in certain situations. -Place the WebRTC streamer configuration at `/var/lib/anbox/streamer.json` within the [instance](https://discourse.ubuntu.com/t/26204#instance) before the Anbox runtime starts. The configuration can be shipped as part of an [application](https://discourse.ubuntu.com/t/managing-applications/17760) or an [addon](https://discourse.ubuntu.com/t/managing-addons/17759). +Place the WebRTC streamer configuration at `/var/lib/anbox/streamer.json` within the instance before the Anbox runtime starts. The configuration can be shipped as part of an application or an addon. The configuration file uses the JSON format. It has the following structure: diff --git a/reuse/links.txt b/reuse/links.txt new file mode 100644 index 00000000..04cfff56 --- /dev/null +++ b/reuse/links.txt @@ -0,0 +1,4 @@ +.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ +.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs +.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs +.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ diff --git a/scripts/generate-ams-config.py b/scripts/generate-ams-config.py deleted file mode 100644 index a4af4d66..00000000 --- a/scripts/generate-ams-config.py +++ /dev/null @@ -1,38 +0,0 @@ -import yaml - -replace_string = "\n") - outfile.write("\n\n") - - for line in infile: - # Replace the "" lines with the table for "xxx" - if line.startswith(replace_string): - which = line[len(replace_string):].replace("-->","").strip() - outfile.write(tables[which]) - # Copy the other lines from the template - else: - outfile.write(line) diff --git a/scripts/publish-pr.py b/scripts/publish-pr.py deleted file mode 100644 index b7fa8c35..00000000 --- a/scripts/publish-pr.py +++ /dev/null @@ -1,19 +0,0 @@ -import requests, json -import sys -import subprocess - -if len(sys.argv) != 2: - print("You must provide the PR number!") - exit(1) -else: - pr = sys.argv[1] - - url = requests.get("https://api.github.com/repos/canonical/anbox-cloud-docs/pulls/"+pr+"/files?per_page=100") - data = json.loads(url.text) - - for one in data: - filename = one['filename'] - if (filename == "reference/ams-configuration.yaml") or (filename == "reference/ams-configuration.tmpl.md"): - filename = "reference/ams-configuration.md" - print("Publish "+filename) - subprocess.call("./publish.sh "+filename, shell=True) diff --git a/scripts/publish.py b/scripts/publish.py deleted file mode 100644 index 811036a5..00000000 --- a/scripts/publish.py +++ /dev/null @@ -1,65 +0,0 @@ -import os -import sys -import requests -import tempfile - -index_file = "index.md" -index_file_ID = "17029" -discourse_prefix = "https://discourse.ubuntu.com/" -difftool = "meld" -discedit = "discedit" - -if "DISCEDIT" in os.environ: - discedit = os.environ['DISCEDIT'] - -# mapping contains file names and their Discourse topic IDs -mapping = {index_file: index_file_ID} - -# Read the mapping from the index file -with open(index_file,"r") as input: - nav = 0 - - for line in input: - # Only process content between "Navigation" and "Redirects" - if line.find("## Navigation") >= 0: - nav = 1 - continue - elif line.find("## Redirects") >= 0: - nav = 0 - continue - if nav: - row = line.split("|") - # If the link is a Discourse topic, use the URL as file name - # and extract the topic ID - if len(row) > 3 and row[3].find("discourse.ubuntu.com") >= 0: - url = row[2].strip() - ID = row[3].strip()[-6:-1] - mapping[url+".md"]= ID - -if len(sys.argv) != 2: - print("You must provide one file name!") - exit(1) -else: - filename = sys.argv[1] - # If we know the topic ID for the given file name - if filename in mapping: - - # Download the current version of the file and diff it to - # the file on disk - with tempfile.NamedTemporaryFile(delete=False) as f: - r = requests.get(discourse_prefix+"raw/"+mapping[filename]) - f.write(r.content) - f.write(b'\n') # Discourse file is missing a newline at the end - oldfile = f.name - f.close() - os.system("diff "+oldfile+" "+filename) - os.unlink(oldfile) - - # Set the editor environment variable to the difftool plus the file - # on disk and start discedit on the corresponding topic ID - # to diff the disk file with the file opened by discedit - os.environ['EDITOR'] = difftool+" "+filename - os.system(discedit+" "+discourse_prefix+"t/"+mapping[filename]) - else: - print("The file name is not in the mapping file.") - exit(1) diff --git a/tutorial/creating-addon.md b/tutorial/creating-addon.md index 0b519ac2..ccc346da 100644 --- a/tutorial/creating-addon.md +++ b/tutorial/creating-addon.md @@ -1,6 +1,10 @@ -This tutorial guides you through the creation of a simple [addon](https://discourse.ubuntu.com/t/managing-addons/17759). The addon that we create in this tutorial is an example for enabling SSH access on a container. +(tut-create-addon)= +# Create an addon + +This tutorial guides you through the creation of a simple addon. The addon that we create in this tutorial is an example for enabling SSH access on a container. + +## Write the addon metadata -## 1. Write the addon metadata In a new `ssh-addon` directory, create a `manifest.yaml` file with the following content: ```yaml name: ssh @@ -8,7 +12,8 @@ description: | Enable SSH access when starting a container ``` -## 2. Add a hook +## Add a hook + Next to your `manifest.yaml` file in the `ssh-addon` directory, create a `hooks` directory. This is where we'll put the hooks we want to implement. Hooks can be implemented in any language, but we are using a bash script here. @@ -31,14 +36,12 @@ Make the file executable. To do so, enter the following command (in the `ssh-add chmod +x hooks/pre-start ``` -[note type="information" status="Tip"] - +```{tip} - Supported hooks are `pre-start`, `post-start` and `post-stop`. - Use the `INSTANCE_TYPE` variable to distinguish between regular and base instances. -See [Hooks](https://discourse.ubuntu.com/t/hooks/28555) for more information. -[/note] - +See {ref}`ref-hooks` for more information. +``` Create an SSH key in your addon directory and move the private key to a location outside of the addon directory (for example, your home directory): ```bash ssh-keygen -f ssh-addon-key -t ecdsa -b 521 @@ -46,7 +49,8 @@ mv ssh-addon-key ~/ ``` Alternatively, you can use an existing key and move the public key into the addon directory. -## 3. Create the addon +## Create the addon + Your addon structure currently looks like this: ```bash ssh-addon @@ -66,7 +70,8 @@ When your addon is created, you can view it with: amc addon list ``` -## 4. Use the addon in an application +## Use the addon in an application + Create an application manifest file (`my-application/manifest.yaml`) and include the addon name under `addons`: ```yaml @@ -90,17 +95,22 @@ The `amc wait` command returns when your application is ready to launch. You can amc launch my-application --service +ssh ``` -The SSH port 22 is closed by default. In the above command, we open it by [exposing its service](https://discourse.ubuntu.com/t/24326) by using `--service`.[/note] +```{note} +The SSH port 22 is closed by default. In the above command, we open it by exposing its service by using `--service`. See {ref}`howto-expose-services` for more information. +``` You can now access your container via SSH: ```bash ssh -i ~/ssh-addon-key root@ -p ``` -[note type="information" status="Note"] The exposed port can be found be running `amc ls`, under the `ENDPOINTS` column. Exposed ports usually start around port 10000.[/note] +```{note} +The exposed port can be found be running `amc ls`, under the `ENDPOINTS` column. Exposed ports usually start around port 10000. +``` -## More information +## Related topics -* [Addon reference](https://discourse.ubuntu.com/t/addons/25293) -* [How to update addons](https://discourse.ubuntu.com/t/update-addons/25286) -* [Extend an application](https://discourse.ubuntu.com/t/extand-an-application/28554) +* {ref}`exp-addons` +* {ref}`howto-update-addons` +* {ref}`howto-extend-application` +* {ref}`ref-addon-manifest` diff --git a/tutorial/getting-started-aaos.md b/tutorial/getting-started-aaos.md index b640bb49..71c532ab 100644 --- a/tutorial/getting-started-aaos.md +++ b/tutorial/getting-started-aaos.md @@ -1,3 +1,6 @@ +(tut-aaos)= +# Get started with an AAOS application + This tutorial guides you through basic operations that you can do with an application based on an Android Automotive OS (AAOS) image. In this tutorial, we will be focusing on the following tasks: @@ -8,7 +11,7 @@ In this tutorial, we will be focusing on the following tasks: ## Prerequisites We will use the appliance dashboard to perform the tasks for this tutorial. So if you haven’t installed the Anbox Cloud Appliance yet, you must do that first. -Follow the installation instructions available at [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/22681) to install and initialise the appliance. Proceed with the tutorial when you can access the appliance dashboard. +Follow the installation instructions available at {ref}`tut-installing-appliance` to install and initialise the appliance. Proceed with the tutorial when you can access the appliance dashboard. ## Create an AAOS-based application @@ -23,7 +26,7 @@ Now, let's enter the values required for creating the application: - *Application name*: `my-app` - *Resource-type*: `a4.3` - The default value of a4.3 is sufficient for this tutorial. Resource type indicates a [pre-defined set of resources](https://discourse.ubuntu.com/t/application-manifest/24197#instance-type-1) that will be made available for your application. + The default value of a4.3 is sufficient for this tutorial. Resource type indicates a {ref}`pre-defined set of resources ` that will be made available for your application. - *Create the image in a*: `Container` Your choice of whether to create the associated image in a container or a virtual machine. @@ -75,4 +78,4 @@ Now, let's try setting the temperature of the automotive: Learn about the various [supported system properties in the VHAL](https://source.android.com/docs/automotive/vhal/system-properties). -You can also use the [Anbox HTTP API](https://discourse.ubuntu.com/t/anbox-http-api/17819#heading--10vhal) to adjust the properties using the CLI. +You can also use the {ref}`Anbox HTTP API ` to adjust the properties using the CLI. diff --git a/tutorial/getting-started-dashboard.md b/tutorial/getting-started-dashboard.md index b39c8776..4c1d1180 100644 --- a/tutorial/getting-started-dashboard.md +++ b/tutorial/getting-started-dashboard.md @@ -1,19 +1,25 @@ -This tutorial guides you through the first steps of using Anbox Cloud. You will learn how to create and access a virtual Android device or an application using the [web dashboard](https://discourse.ubuntu.com/t/web-dashboard/20871). +(tut-getting-started-dashboard)= +# Getting started with Anbox Cloud (web dashboard) -The web dashboard provides an easy-to use interface to Anbox Cloud. However, it currently supports a limited set of functionality, which means that it might not be sufficient for all use cases. If you want to learn how to manage Anbox Cloud from the command line, see the [Get started with Anbox Cloud (CLI)](https://discourse.ubuntu.com/t/getting-started/17756) tutorial. +This tutorial guides you through the first steps of using Anbox Cloud. You will learn how to create and access a virtual Android device or an application using the web dashboard. + +The web dashboard provides an easy-to use interface to Anbox Cloud. However, it currently supports a limited set of functionality, which means that it might not be sufficient for all use cases. If you want to learn how to manage Anbox Cloud from the command line, see the {ref}`tut-getting-started-cli` tutorial. ## Preparation If you haven't installed Anbox Cloud or the Anbox Cloud Appliance yet, you must do so before you can continue with this tutorial. See the following documentation for installation instructions: -- [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702) -- [How to install Anbox Cloud](https://discourse.ubuntu.com/t/install-anbox-cloud/24336) (note that you must install the streaming stack for the web dashboard to be available) +- {ref}`howto-install-appliance` +- {ref}`howto-install-anbox-cloud` -## 1. Create a virtual device +(sec-create-virtual-device)= +## Create a virtual device Let's start exploring what Anbox Cloud can do by launching a virtual device that runs a specific Android version. -[note type="information" status="Note"]With "virtual device" we mean a simulated device that runs a plain Android operating system without any special apps installed. Technically speaking, Anbox Cloud treats such a virtual device as an "empty" application, thus an application that is not running a specific APK.[/note] +```{note} +With "virtual device" we mean a simulated device that runs a plain Android operating system without any special apps installed. Technically speaking, Anbox Cloud treats such a virtual device as an "empty" application, thus an application that is not running a specific APK. +``` Complete the following steps to create a virtual device: @@ -28,7 +34,7 @@ Complete the following steps to create a virtual device: ![Add application](https://assets.ubuntu.com/v1/7cb08440-add-application.png) 8. You are redirected to the application view. Wait until the application status changes to `ready`. -## 2. Launch and test the virtual device +## Launch and test the virtual device When the application has been initialised and its status changes to `ready`, complete the following steps to launch and test the virtual device: @@ -42,19 +48,21 @@ When the application has been initialised and its status changes to `ready`, com ![Stream the virtual device](https://assets.ubuntu.com/v1/9d9ba326-interact-virtual-device.png) -## 3. Create an application from an APK +## Create an application from an APK -To create an application for a specific Android app, follow the steps in [1. Create a virtual device](#h-1-create-a-virtual-device-2), but upload the APK of the Android app. +To create an application for a specific Android app, follow the steps in {ref}`sec-create-virtual-device`, but upload the APK of the Android app. -[note type="information" status="Important"]Not all Android apps are compatible with Anbox Cloud. See [How to port Android apps](https://discourse.ubuntu.com/t/port-android-apps/17776) for more information.[/note] +```{important} +Not all Android apps are compatible with Anbox Cloud. See {ref}`howto-port-android-apps` for more information. +``` -Choose a [resource preset](https://discourse.ubuntu.com/t/application-manifest/24197#resources-7) suitable for your application. If your instance is equipped with a GPU and your application requires the use of the GPU for rendering and video encoding, make sure to mention the GPU requirement using the `resources` attribute. Otherwise, the container will use a GPU if available or software encoding. +Choose a {ref}`resource preset ` suitable for your application. If your instance is equipped with a GPU and your application requires the use of the GPU for rendering and video encoding, make sure to mention the GPU requirement using the `resources` attribute. Otherwise, the container will use a GPU if available or software encoding. You can launch and test the application in the same way as you did for the virtual device. -## 4. Update an application +## Update an application -You can have several versions of an application. See [How to update an application](https://discourse.ubuntu.com/t/update-an-application/24201) for detailed information. +You can have several versions of an application. See {ref}`howto-update-application` for detailed information. Complete the following steps to add a new version to your application: @@ -63,17 +71,17 @@ Complete the following steps to add a new version to your application: 3. Upload a new APK, or do other changes to the configuration. 4. Click **Update application**. -## 5. Delete an application +## Delete an application While following this tutorial, you created several applications. You can see them in the application view at `https:///applications`. To delete an application, click the **Delete application** button in the **Actions** column and confirm the deletion. -[note type="information" status="Tip"] +```{tip} To skip the confirmation window, hold **Shift** when clicking the **Delete application** button. -[/note] +``` -## 6. Inspect instances +## Inspect instances Every time you start a session for an application, Anbox Cloud creates an instance. The instance keeps running even if you exit the stream, until you either stop the session by clicking **Stop session** or delete the instance. @@ -103,6 +111,10 @@ Complete the following steps to inspect an instance: You now know how to use the web dashboard to create, launch and test applications in Anbox Cloud. -If you are interested in more advanced use cases, check out the [Get started with Anbox Cloud (CLI)](https://discourse.ubuntu.com/t/getting-started/17756) tutorial to learn how to use Anbox Cloud from the command line. +If you are interested in more advanced use cases, check out the {ref}`tut-getting-started-cli` tutorial to learn how to use Anbox Cloud from the command line. + +## Related topics -Also see the documentation about [How to manage applications](https://discourse.ubuntu.com/t/manage-applications/24333) and [How to work with instances](https://discourse.ubuntu.com/t/24335). +* {ref}`howto-use-web-dashboard` +* {ref}`howto-manage-applications` +* {ref}`howto-instance` diff --git a/tutorial/getting-started.md b/tutorial/getting-started.md index e973e3e1..1ef9a6de 100644 --- a/tutorial/getting-started.md +++ b/tutorial/getting-started.md @@ -1,29 +1,34 @@ -This tutorial guides you through the first steps of managing Anbox Cloud from the command line. You will learn how to communicate with [AMS](https://discourse.ubuntu.com/t/about-ams/24321) and how to create and access a virtual Android device or an application. +(tut-getting-started-cli)= +# Getting started with Anbox Cloud (CLI) -The tutorial focuses on using the command line to work with Anbox Cloud, which gives you access to all features of Anbox Cloud. Alternatively, you can use the [web dashboard](https://discourse.ubuntu.com/t/web-dashboard/20871), which provides a simpler user interface but does not support all functionality. See the [Get started with Anbox Cloud (web dashboard)](https://discourse.ubuntu.com/t/getting-started-with-anbox-cloud-web-dashboard/24958) tutorial for an introduction on how to use the web dashboard. +This tutorial guides you through the first steps of managing Anbox Cloud from the command line. You will learn how to communicate with the {ref}`exp-ams` (AMS) and how to create and access a virtual Android device or an application. + +The tutorial focuses on using the command line to work with Anbox Cloud, which gives you access to all features of Anbox Cloud. Alternatively, you can use the web dashboard, which provides a simpler user interface but does not support all functionality. + +See the {ref}`tut-getting-started-dashboard` tutorial for an introduction to and {ref}`howto-use-web-dashboard` for detailed instructions on using the web dashboard. ## Preparation If you haven't installed Anbox Cloud or the Anbox Cloud Appliance yet, you must do so before you can continue with this tutorial. See the following documentation for installation instructions: -* [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702) -* [How to install Anbox Cloud](https://discourse.ubuntu.com/t/install-anbox-cloud/24336) +* {ref}`howto-install-appliance` +* {ref}`howto-install-anbox-cloud` -## 1. Run AMC +## Run AMC -The Anbox Management Client `amc` communicates with the [Anbox Management Service (AMS)](https://discourse.ubuntu.com/t/about-ams/24321). You will use `amc` to manage all aspects of Anbox Cloud that are related to AMS. +The Anbox Management Client `amc` communicates with the AMS. You will use `amc` to manage all aspects of Anbox Cloud that are related to AMS. How and where to run `amc` depends on your use case: - If you are running the Anbox Cloud Appliance on AWS, `amc` is already installed on the machine that runs the appliance. Log on to that machine to run `amc`. Note that you must use the user name `ubuntu` and provide the path to your private key file when connecting. See [Connect to your Linux instance using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html) for instructions on how to connect. -- If you are running the Anbox Cloud Appliance on a physical or virtual machine, log on to that machine and ensure that you have [enabled the `anbox-cloud` service using the Ubuntu Pro client](https://discourse.ubuntu.com/t/install-the-anbox-cloud-appliance-on-a-dedicated-machine/22681#h-3-enable-the-anbox-cloud-service-using-the-ubuntu-pro-client-5). +- If you are running the Anbox Cloud Appliance on a physical or virtual machine, log on to that machine and ensure that you have performed the instructions mentioned in {ref}`sec-enable-anbox-pro`. - If you are running a full Anbox Cloud deployment, access the `ams/0` machine to run `amc`. You can do this by opening an SSH session with the `juju` command: juju ssh ams/0 -- If you want to run `amc` on your local Ubuntu-based development machine against a remote Anbox Cloud installation, follow the instructions in [How to control AMS remotely](https://discourse.ubuntu.com/t/managing-ams-access/17774). +- If you want to run `amc` on your local Ubuntu-based development machine against a remote Anbox Cloud installation, follow the instructions in {ref}`howto-access-ams-remote`. To ensure that `amc` is available, run the following command: @@ -33,9 +38,13 @@ To check if `amc` is set up to access the correct AMS, run the following command amc remote list -## 2. Ensure images are available +## Ensure images are available + +The next step is to check whether AMS has synchronised all images from the Canonical hosted image server. To list all the synchronised images, run: -Next, check whether AMS has synchronised all images from the Canonical hosted image server. You can list all synchronised images with the `amc image ls` command: + amc image ls + +The output should look similar to: ```bash +----------------------+------------------------+--------+----------+--------------+---------+ @@ -45,19 +54,17 @@ Next, check whether AMS has synchronised all images from the Canonical hosted im +----------------------+------------------------+--------+----------+--------------+---------+ | cgrqjnmk9eqlsruefco0 | jammy:android12:arm64 | active | 1 | aarch64 | false | +----------------------+------------------------+--------+----------+--------------+---------+ -| cgrqk2uk9eqlsruefcog | jammy:android11:arm64 | active | 1 | aarch64 | false | -+----------------------+------------------------+--------+----------+--------------+---------+ ``` -See [Provided images](https://discourse.ubuntu.com/t/provided-images/24185) for more information. - If the images are not yet available, wait a few minutes, then try again. -## 3. Create a virtual device +## Create a virtual device Let's start exploring what Anbox Cloud can do by launching a virtual device that runs a specific Android version. -[note type="information" status="Note"]With "virtual device" we mean a simulated device that runs a plain Android operating system without any special apps installed. Technically speaking, Anbox Cloud treats such a virtual device as an "empty" application, thus an application that is not running a specific APK.[/note] +```{note} +With "virtual device" we mean a simulated device that runs a plain Android operating system without any special apps installed. Technically speaking, Anbox Cloud treats such a virtual device as an "empty" application, thus an application that is not running a specific APK. +``` Complete the following steps to create a virtual device: @@ -75,7 +82,7 @@ Complete the following steps to create a virtual device: amc application create /path/to/manifest/directory/ -3. The application is now being [bootstrapped](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2). Enter the following command to monitor the progress: +3. The application is now being {ref}`bootstrapped `. Enter the following command to monitor the progress: watch -n 1 amc application ls @@ -89,7 +96,7 @@ Complete the following steps to create a virtual device: +----------------------+--------------------+---------------+--------+------+-----------+--------+---------------------+ ``` -## 4. Log on to the virtual device +## Log on to the virtual device When the application for the virtual device is ready, you can launch it and log on to it: @@ -117,7 +124,9 @@ When the application for the virtual device is ready, you can launch it and log You can find the container ID of the virtual device in the list of containers. - [note type="information" status="Tip"]You can use tab completion when entering the container ID.[/note] + ```{tip} + You can use tab completion when entering the container ID. + ``` 4. You are now inside the Linux container that runs the Android container. To access the nested Android container, enter the following command: anbox-shell @@ -125,9 +134,9 @@ When the application for the virtual device is ready, you can launch it and log 5. Enter some commands. For example, enter `ls` to display the files inside the Android container, or `logcat` to display the logs. 6. Enter `exit` or press `Ctrl`+`D` once to exit the Android shell, and then again to exit the Linux container. -## 5. Test the virtual device +## Test the virtual device -You can test the virtual device by connecting to it from your local machine and mirroring its screen. To do so, use the `scrcpy` tool. See [How to access a container with scrcpy](https://discourse.ubuntu.com/t/container-access/17772#access-an-instance-with-scrcpy-2) for more detailed instructions. +You can test the virtual device by connecting to it from your local machine and mirroring its screen. To do so, use the `scrcpy` tool. See {ref}`sec-access-instance-scrcpy` for more detailed instructions. If you do not have `scrcpy` installed on your local machine, enter the following command to install it: @@ -168,11 +177,13 @@ To connect to your virtual device with `scrcpy`, complete the following steps: scrcpy -## 6. Create an application from an APK +## Create an application from an APK Creating an application for a specific Android app is very similar to creating a virtual device, except that you provide an APK of the Android app when creating the Anbox Cloud application. -[note type="information" status="Important"]Not all Android apps are compatible with Anbox Cloud. See [How to port Android apps](https://discourse.ubuntu.com/t/port-android-apps/17776) for more information.[/note] +```{important} +Not all Android apps are compatible with Anbox Cloud. See {ref}`howto-port-android-apps` for more information. +``` Complete the following steps to create an application from an APK: @@ -180,7 +191,7 @@ Complete the following steps to create an application from an APK: 2. Create a `manifest.yaml` file in that folder. This manifest contains the application name and if necessary, define resources for the application. If your instance is equipped with a GPU and your application requires the use of the GPU for rendering and video encoding, make sure to mention the GPU requirement using the `resources` attribute. Otherwise, the container will use a GPU if available or software encoding. -If no specific resources are mentioned, the [default resource preset](https://discourse.ubuntu.com/t/24960) is used. +If no specific resources are mentioned, the {ref}`default resource preset ` is used. For example, the file could look like this: @@ -192,22 +203,24 @@ If no specific resources are mentioned, the [default resource preset](https://di disk-size: 8GB ``` - [note type="information" status="Tip"]The manifest can also contain more advanced configuration like [Addons](https://discourse.ubuntu.com/t/managing-addons/17759), permissions and others. For more information about the manifest format, see [Application manifest](https://discourse.ubuntu.com/t/application-manifest/24197) documentation.[/note] + ```{tip} + The manifest can also contain more advanced configuration like {ref}`exp-addons`, permissions and others. For more information about the manifest format, see {ref}`ref-application-manifest` documentation. + ``` 2. Enter the following command to create the application, replacing */path/to/manifest/directory/* with the path to the directory where you created the manifest file: amc application create /path/to/manifest/directory/ -3. The application is now being [bootstrapped](https://discourse.ubuntu.com/t/managing-applications/17760#bootstrap-process-2). Enter the following command to monitor the progress: +3. The application is now being {ref}`bootstrapped `. Enter the following command to monitor the progress: watch -n 1 amc application ls Wait until the status of the application changes to `ready`. -When the application is ready, you can launch it and then test it in the same way as the virtual device by either [logging on to it](#h-4-log-on-to-the-virtual-device-5) or [connecting to it with `scrcpy`](#h-5-test-the-virtual-device-6). +When the application is ready, you can launch it and then test it in the same way as the virtual device by either [logging on to it](#log-on-to-the-virtual-device) or [connecting to it with `scrcpy`](#test-the-virtual-device). -## 7. Update an application +## Update an application -You can have several versions of an application. See [How to update an application](https://discourse.ubuntu.com/t/update-an-application/24201) for detailed information. +You can have several versions of an application. See {ref}`howto-update-application` for detailed information. Complete the following steps to add a new version to your application: @@ -238,7 +251,7 @@ Complete the following steps to add a new version to your application: When you launch an application without explicitly specifying a version, AMS uses the latest published version of the application. Therefore, when you now launch the application again, the new version of your application is selected and the ADB service is exposed automatically. -## 8. List and delete applications and containers +## List and delete applications and containers While following this tutorial, you created several applications and containers. Let's check them out and delete the ones that aren't needed anymore: @@ -297,6 +310,11 @@ You now know how to use the command line to create, launch and test applications This tutorial used a container to illustrate how to create and work with applications using Anbox Cloud. Alternatively, you can also use a virtual machine instead of a container by using the `--vm` option with the `amc` commands. -If you are interested in a more easy-to-use interface, check out the [Get started with Anbox Cloud (web dashboard)](https://discourse.ubuntu.com/t/getting-started-with-anbox-cloud-web-dashboard/24958) tutorial to learn how to manage Anbox Cloud using the [web dashboard](https://discourse.ubuntu.com/t/web-dashboard/20871). +If you are interested in a more easy-to-use interface, check out the {ref}`tut-getting-started-dashboard` tutorial to learn how to manage Anbox Cloud using the web dashboard. + +## Related topics -Also see the documentation about [How to manage applications](https://discourse.ubuntu.com/t/manage-applications/24333) and [How to work with instances](https://discourse.ubuntu.com/t/24335) for more in-depth information. +* {ref}`howto-use-web-dashboard` +* {ref}`howto-manage-applications` +* {ref}`howto-instance` +* {ref}`ref-provided-images` diff --git a/tutorial/installing-appliance.md b/tutorial/installing-appliance.md index b52add4b..37a8d5be 100644 --- a/tutorial/installing-appliance.md +++ b/tutorial/installing-appliance.md @@ -1,36 +1,44 @@ -The Anbox Cloud Appliance provides a deployment of Anbox Cloud to a single machine. This offering is well suited for initial prototype and small scale deployments. +(tut-installing-appliance)= +# Install the appliance on a dedicated machine -There are differences between the Anbox Cloud Appliance and the full Anbox Cloud installation (see [Variants](https://discourse.ubuntu.com/t/anbox-cloud/17802#variants-1)). This tutorial focuses on installing the **Anbox Cloud Appliance** on a single dedicated machine. +The Anbox Cloud Appliance provides a deployment of Anbox Cloud to a single machine. This offering is well suited for initial prototype and small scale deployments. - [note type="caution" status="Warning"]Remember that installing the Anbox Cloud Appliance will take over the entire instance, install packages and override existing components to configure them as required. If you have existing components, for example, LXD containers, installing and initialising the appliance could override any existing configuration. Hence, it is important to try this tutorial on a machine dedicated for Anbox Cloud.[/note] +There are differences between the Anbox Cloud Appliance and the full Anbox Cloud installation (see {ref}`sec-variants`). This tutorial focuses on installing the **Anbox Cloud Appliance** on a single dedicated machine. +```{caution} +Remember that installing the Anbox Cloud Appliance will take over the entire instance, install packages and override existing components to configure them as required. If you have existing components, for example, LXD containers, installing and initialising the appliance could override any existing configuration. Hence, it is important to try this tutorial on a machine dedicated for Anbox Cloud. +``` -If you want to install **Anbox Cloud** instead, see [How to install Anbox Cloud](https://discourse.ubuntu.com/t/install-anbox-cloud/24336) or if you want to install the appliance on a cloud platform, see [How to install the Anbox Cloud Appliance](https://discourse.ubuntu.com/t/how-to-install-the-anbox-cloud-appliance/29702). +If you want to install **Anbox Cloud** instead, see {ref}`howto-install-anbox-cloud` or if you want to install the appliance on a cloud platform, see {ref}`howto-install-appliance`. This tutorial guides you through the steps that are required to install and initialise the Anbox Cloud Appliance on the machine from the [snap](https://snapcraft.io/anbox-cloud-appliance). -## Check the prerequisites +## Prerequisites Make sure you have the following prerequisites: -* An Ubuntu SSO account. If you don't have one yet, create it [here](https://login.ubuntu.com). -* A virtual or bare metal machine running Ubuntu 20.04 or 22.04. See the detailed requirements [here](https://discourse.ubuntu.com/t/requirements/17734). - [note type="caution" status="Warning"]It is not recommended to run Anbox Cloud on an Ubuntu desktop appliance. Always use the [server](https://ubuntu.com/download/server) or the [cloud](https://ubuntu.com/download/cloud) variant.[/note] -* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to https://ubuntu.com/pro to retrieve it. - [note type="caution" status="Warning"]The *Ubuntu Pro (Infra-only)* token does **NOT** work and will result in a failed deployment. You need an *Ubuntu Pro* subscription.[/note] +* An Ubuntu SSO account. If you don't have one yet, [create it](https://login.ubuntu.com). +* A virtual or bare metal machine running Ubuntu 20.04 or 22.04. See the detailed {ref}`ref-requirements`. +```{caution} +It is not recommended to run Anbox Cloud on an Ubuntu desktop appliance. Always use the [server](https://ubuntu.com/download/server) or the [cloud](https://ubuntu.com/download/cloud) variant. +``` +* Your Ubuntu Pro token for an Ubuntu Pro subscription. If you don't have one yet, [speak to your Canonical representative](https://anbox-cloud.io/contact-us). If you already have a valid Ubuntu Pro token, log in to [Ubuntu Pro](https://ubuntu.com/pro) to retrieve it. +```{caution} +The *Ubuntu Pro (Infra-only)* token does not work and will result in a failed deployment. You need an *Ubuntu Pro* subscription. +``` ## Install the appliance The following instructions guide you through all relevant steps to install the Anbox Cloud Appliance from the [snap](https://snapcraft.io/anbox-cloud-appliance). -### 1. Update your system +### Update your system On your machine, run the following commands to ensure that all installed packages on your system are up-to-date: sudo apt update sudo apt upgrade -### 2. Attach your machine to the Ubuntu Pro subscription +### Attach your machine to Ubuntu Pro The Anbox Cloud Appliance requires a valid Ubuntu Pro subscription. @@ -38,7 +46,8 @@ Before installing the appliance, you must attach the machine on which you want t sudo pro attach -### 3. Enable the `anbox-cloud` service using the Ubuntu Pro client. +(sec-enable-anbox-pro)= +### Enable the `anbox-cloud` service On your machine, run the following command to install the Anbox Cloud Appliance and additional dependencies. @@ -51,20 +60,25 @@ Running this command does the following: * [Anbox Management Client (AMC)](https://snapcraft.io/amc) * [LXD](https://snapcraft.io/lxd) - [note type="information" status="Important"] The Anbox Cloud Appliance requires LXD >= 5.0 and hence LXD is installed from the `5.0/stable` track by default. If LXD is already installed but the version is earlier than 5.0, run `snap refresh --channel=5.0/stable lxd` to update it. However, if LXD version is later than 5.0, [do not downgrade it as it may render LXD unusable](https://documentation.ubuntu.com/lxd/en/latest/installing/#upgrade-lxd).[/note] + ```{important} + The Anbox Cloud Appliance requires LXD >= 5.0 and hence LXD is installed from the `5.0/stable` track by default. If LXD is already installed but the version is earlier than 5.0, run `snap refresh --channel=5.0/stable lxd` to update it. However, if LXD version is later than 5.0, [do not downgrade it as it may render LXD unusable](https://documentation.ubuntu.com/lxd/en/latest/installing/#upgrade-lxd). + ``` 1. Installs `anbox-cloud-appliance` snap from the `latest/stable` track. 1. Configures the `apt` repositories for Anbox Cloud. +(sec-initialise-appliance)= ## Initialise the appliance After the installation, access the appliance in your web browser by entering the IP of your machine (in the following steps referred to as `https://your-machine-address`). This web page provides status information for the following initialisation process. -[note type="information" status="Note"]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.[/note] +```{note} +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) -### 1. Start the initialisation process +### Run the `init` command On your machine, enter the following command to invoke the initialisation process of the Anbox Cloud Appliance: @@ -72,7 +86,7 @@ On your machine, enter the following command to invoke the initialisation proces You will be asked a few questions. If you don't want to make any specific changes, you can safely stay with the offered default answers. When the command returns, the initialisation process will run fully automatically in the background. -### 2. Monitor the progress +### Monitor the progress You can watch the status web page at `https://your-machine-address` for progress information. @@ -87,27 +101,27 @@ update-available: false reboot-needed: false version: 1.22.0 ``` - +(sec-register-dashboard)= ## Register with the dashboard -Once the initialisation process has finished, you are presented with a welcome page on `https://your-machine-address` with instructions on how to register a user account with your installation. This registration is needed to access the [web dashboard](https://discourse.ubuntu.com/t/web-dashboard/20871). +Once the initialisation process has finished, you are presented with a welcome page on `https://your-machine-address` with instructions on how to register a user account with your installation. This registration is needed to access the {ref}`exp-web-dashboard`. ![Instructions for registering Ubuntu SSO account|690x442](https://assets.ubuntu.com/v1/93b47634-install_appliance_register.png) -### 1. Register your Ubuntu SSO account +### Register your Ubuntu SSO account -Enter the following command to register your Ubuntu SSO account: +Enter the following command to register your Ubuntu SSO account with the appliance dashboard: anbox-cloud-appliance dashboard register The output provides a link that you must open in your web browser to finish the account creation. By default, the registration link expires after one hour. After registering, you can log into the appliance dashboard with your Ubuntu SSO account. -### 2. Log into the appliance dashboard +### Log into the appliance dashboard After registering, you can log into the appliance dashboard at `https://your-machine-address` with your Ubuntu SSO account. ## Done! -Your Anbox Cloud Appliance is now fully set up and ready to be used! Next, you should check out the [Get started with Anbox Cloud (web dashboard)](https://discourse.ubuntu.com/t/getting-started-with-anbox-cloud-web-dashboard/24958) or the [Get started with Anbox Cloud (CLI)](https://discourse.ubuntu.com/t/getting-started/17756) tutorial to familiarise yourself with how to use Anbox Cloud. +Your Anbox Cloud Appliance is now fully set up and ready to be used! Next, you should check out the {ref}`tut-getting-started-dashboard` or the {ref}`tut-getting-started-cli` tutorial to familiarise yourself with how to use Anbox Cloud. You can find more information about how to use the appliance in the documentation. The appliance installation is nearly identical to installing via Juju, so all the commands and examples not relating directly to Juju will apply. diff --git a/tutorial/landing.md b/tutorial/landing.md index 5c4211b4..0648b896 100644 --- a/tutorial/landing.md +++ b/tutorial/landing.md @@ -1,13 +1,27 @@ +(tutorials)= +# Tutorials + This section of our documentation helps you learn the installation process of the Anbox Cloud Appliance and go through the first steps of using Anbox Cloud. Our tutorials aim to make as few assumptions as possible and provide a learning experience as you begin using Anbox Cloud. The following tutorials help you install the Anbox cloud Appliance and start using it either through the web dashboard or through the command line interface: -1. [Install the Anbox Cloud Appliance on a dedicated machine](https://discourse.ubuntu.com/t/22681) -1. [Get started with Anbox Cloud using the web dashboard](https://discourse.ubuntu.com/t/24958) -1. [Get started with Anbox Cloud using the command line interface](https://discourse.ubuntu.com/t/17756) +1. {ref}`tut-installing-appliance` +1. {ref}`tut-getting-started-dashboard` +1. {ref}`tut-getting-started-cli` The following tutorials are optional and help you further explore features of Anbox Cloud: -1. [Set up a stream client](https://discourse.ubuntu.com/t/set-up-a-stream-client/37328) -1. [Get started with AAOS](https://discourse.ubuntu.com/t/create-and-stream-an-aaos-application/45467) -1. [Create an addon](https://discourse.ubuntu.com/t/25284) +1. {ref}`tut-set-up-stream-client` +1. {ref}`tut-aaos` +1. {ref}`tut-create-addon` + +Also check out the {ref}`how-to-guides` for instructions on how to achieve specific goals when using Anbox Cloud, as well as the {ref}`reference` and {ref}`explanation` sections for other helpful information. + +```{toctree} +:hidden: -Also check out the [How-to guides](https://discourse.ubuntu.com/t/how-to-guides/28827) for instructions on how to achieve specific goals when using Anbox Cloud, as well as the [Reference](https://discourse.ubuntu.com/t/reference/28828) and [Explanation](https://discourse.ubuntu.com/t/explanation/28829) sections for other helpful information. +Install Anbox Cloud Appliance +Getting started (AAOS) +Getting started (dashboard) +Getting started (CLI) +stream-client +creating-addon +``` diff --git a/tutorial/stream-client.md b/tutorial/stream-client.md index 08e22f50..8936e997 100644 --- a/tutorial/stream-client.md +++ b/tutorial/stream-client.md @@ -1,4 +1,7 @@ -This tutorial guides you through the process of setting up a web-based streaming client using the Anbox Cloud streaming stack. The connection between the stream client and the server uses WebRTC backed by web sockets which enable the real time communications required for streaming. To know more about the WebRTC configuration, see [WebRTC streamer](https://discourse.ubuntu.com/t/webrtc-streamer/30195). +(tut-set-up-stream-client)= +# Set up a stream client + +This tutorial guides you through the process of setting up a web-based streaming client using the Anbox Cloud streaming stack. The connection between the stream client and the server uses WebRTC backed by web sockets which enable the real time communications required for streaming. To know more about the WebRTC configuration, see {ref}`ref-webrtc`. ## Preparation @@ -6,7 +9,7 @@ Complete the following preparatory steps: ### Install the Anbox Cloud Appliance -We need the Anbox Cloud streaming stack to be deployed already to set up a streaming client. So let's get the streaming stack ready by installing the Anbox Cloud Appliance. Follow the instructions in the [appliance installation tutorial](https://discourse.ubuntu.com/t/22681) until you finish initialising the Appliance. +We need the Anbox Cloud streaming stack to be deployed already to set up a streaming client. So let's get the streaming stack ready by installing the Anbox Cloud Appliance. Follow the instructions in the {ref}`tut-installing-appliance` tutorial until you finish initialising the Appliance. ### Create an access token @@ -18,17 +21,17 @@ On the machine where Anbox Cloud Appliance is installed, create the service acco The output of this command provides the access token. Make a note of this token to use when you make a request to the stream gateway API. -See [How to access the stream gateway](https://discourse.ubuntu.com/t/how-to-access-the-stream-gateway/17784) for more information on creating, using and deleting the access token. +See {ref}`howto-access-stream-gateway` for more information on creating, using and deleting the access token. ### Download the Anbox Cloud streaming SDK -Download the [Anbox Cloud streaming SDK](https://discourse.ubuntu.com/t/anbox-cloud-sdks/17844#anbox-cloud-streaming-sdk-8) from GitHub: +Download the {ref}`sec-streaming-sdk` from GitHub: git clone https://github.com/canonical/anbox-streaming-sdk.git ### Create an application -Follow the instructions in [How to create an application](https://discourse.ubuntu.com/t/24198) and create an application. You can create any application, the application type does not matter. +Follow the instructions in {ref}`howto-create-application` and create an application. You can create any application, the application type does not matter. ## Set up the stream client @@ -38,7 +41,9 @@ Create a directory to set up the stream client: Create a `demo.html` file inside `/srv/stream-client`: -[note type="information" status="Important"]The inline comments in the following code provide pointers to replace certain values with your corresponding values. For example, you will be required to replace the values of `url`, `authToken`, `app` in the following example with your values. [/note] +```{important} +The inline comments in the following code provide pointers to replace certain values with your corresponding values. For example, you will be required to replace the values of `url`, `authToken`, `app` in the following example with your values. +``` ```html @@ -100,7 +105,7 @@ If you experience any streaming issues, you can turn on debug information by add debug: true, } -See [how to troubleshoot streaming issues](https://discourse.ubuntu.com/t/31341) for common issues related to streaming. +See {ref}`howto-ts-streaming-issues` for common issues related to streaming. ## Create and enable the stream UI service @@ -182,7 +187,7 @@ With HTTP basic authentication configured, users will be asked to enter the cred Now you can go to `https:///demo/`, enter the HTTP basic authentication credentials and view the web-based streaming client. -## Related information +## Related topics * [WebRTC](https://webrtc.org/) * [Traefik](https://traefik.io/)