Skip to main content
Version: 20 Mar 2024

AR Cloud Custom Deployment

This type of deployment is appropriate for any edge computing, on-premises, or any other deployment strategy that does not involve Google Cloud or AWS.

Linux Notice

Unless otherwise specified, these instructions are assumed to be running inside a Debian/Ubuntu Linux environment.

Setup

Install Linux Dependencies

sudo apt update
sudo apt install -y curl gpg sed gettext

Docker

curl https://releases.rancher.com/install-docker/20.10.sh | sh
Docker

Post-installation step:

Manage Docker as a non-root user.

Tools

Helm

Helm

The minimum version requirement is 3.9.x.

Helm 3.13.0

The 3.13.0 version of Helm introduced a bug in the way values are merged. The deployment will not work with this version, so please use version 3.13.1 or newer where the issue is fixed.

Install Helm using apt:

curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
sudo apt-get install apt-transport-https --yes
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm

AR Cloud

Download the latest AR Cloud public release from GitHub:

LATEST_RELEASE=$(curl -sSLH 'Accept: application/json' https://github.com/magicleap/arcloud/releases/latest)
LATEST_VERSION=$(echo $LATEST_RELEASE | sed -e 's/.*"tag_name":"\([^"]*\)".*/\1/')
ARTIFACT_URL="https://github.com/magicleap/arcloud/archive/refs/tags/$LATEST_VERSION.tar.gz"
curl -sSLC - $ARTIFACT_URL | tar -xz
cd arcloud-$LATEST_VERSION

Configure Environment

note

If you do not have a key assigned for Quay.io, please contact Customer Care:

care@magicleap.com

Configure the container registry details:

export REGISTRY_SERVER="quay.io"
export REGISTRY_USERNAME="<username>"
export REGISTRY_PASSWORD="<password>"

Set the cluster namespace where the AR Cloud components will be installed:

export NAMESPACE="arcloud"

Alternatively, make a copy of the setup/env.example file, update the values and source it in your terminal:

cp setup/env.example setup/env.my-cluster
# use your favourite editor to update the setup/env.my-cluster file
. setup/env.my-cluster

Infrastructure Setup

Prepare Your IP Address

The IP address might differ depending on the target platform:

  • for local machines - the loopback interface address (127.0.0.1) or the address of another network interface on the machine (e.g. 192.168.1.101)
  • for cloud providers - the configured/assigned public IP of the instance

To list the available IPv4 addresses on your machine/instance, try the following command:

ip -br a | awk '/UP / { print $1, $3 }'
Caution

Verify that your Magic Leap device has an IP address assigned from the same subnet as your machine or the device is able to access one of the IP addresses from the list above (your router allows connectivity between different subnets).

Set the IP address where AR Cloud will be available:

export DOMAIN="<IPv4 address of your active network adapter>"
note

The DOMAIN variable is already included in the env file described above.

Install Kubernetes

Kubernetes

Recommended Resources:

  • 8 CPUs
  • 32 GB memory
caution

If your computer is connected to more than one network interface (example: WiFi and Ethernet), select which network IP you want to receive the Kubernetes-related traffic.

Remove previous Rancher K3s Kubernetes installation (skip if you do not have K3s installed):

/usr/local/bin/k3s-uninstall.sh

Set the version of K3s to be installed:

export INSTALL_K3S_VERSION=v1.27.3+k3s1

Run setup script:

curl -sfL https://get.k3s.io | sh -s - \
--docker \
--disable traefik \
--write-kubeconfig-mode 600 \
--node-external-ip ${DOMAIN}

Configure K3s service:

sudo rm -rf $HOME/.kube/config && mkdir -p $HOME/.kube
sudo ln -s /etc/rancher/k3s/k3s.yaml $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
sudo chmod 600 $HOME/.kube/config

Verify that the K3s service is running:

systemctl status k3s

Install Istio

curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.18.5 sh -
cd istio-1.18.5
cat ../setup/istio.yaml | envsubst | ./bin/istioctl install -y -f -
note

If you received an error in the last step referring to port 8080, the most likely cause is not having your Kubernetes services running on your host machine.

Install Istio Socket Options

kubectl -n istio-system apply -f ../setup/ingress-gateway-socket-options.yaml

Install Istio Gateway

kubectl -n istio-system apply -f ../setup/gateway.yaml
cd ../

Install ARCloud

Install cert-manager

note

This part is only required if you plan on using a custom domain with a TLS certificate issued automatically.

Make sure that you allow ingress traffic on port 80 on the firewall. By default, the challenge used to issue a certificate temporarily exposes a web service that the issuer connects to to verify ownership of the domain. As there is no list of IPs that the request will come from, access has to be unrestricted. Alternatively, a DNS challenge can be configured by modifying the setup/issuer.yaml file used below.

For local deployments or when using an IP address only, it can be skipped.

Set the version to be installed:

export CERT_MANAGER_VERSION=1.9.1

Install the helm chart, create the namespace and CRDs:

helm upgrade --install --wait --repo https://charts.jetstack.io cert-manager cert-manager \
--version ${CERT_MANAGER_VERSION} \
--create-namespace \
--namespace cert-manager \
--set installCRDs=true

Deploy the issuer with a HTTP challenge:

kubectl -n istio-system apply -f ./setup/issuer.yaml

Deploy the certificate:

cat ./setup/certificate.yaml | envsubst | kubectl -n istio-system apply -f -

Create K8s Namespace

kubectl create namespace ${NAMESPACE}
kubectl label namespace ${NAMESPACE} istio-injection=enabled
kubectl label namespace ${NAMESPACE} pod-security.kubernetes.io/audit=baseline pod-security.kubernetes.io/audit-version=v1.25 pod-security.kubernetes.io/warn=baseline pod-security.kubernetes.io/warn-version=v1.25

Create Container Registry Secret

kubectl --namespace ${NAMESPACE} delete secret container-registry --ignore-not-found
kubectl --namespace ${NAMESPACE} create secret docker-registry container-registry \
--docker-server=${REGISTRY_SERVER} \
--docker-username=${REGISTRY_USERNAME} \
--docker-password=${REGISTRY_PASSWORD}

Setup AR Cloud

./setup.sh \
--set global.domain=${DOMAIN} \
--no-secure \
--no-observability \
--accept-sla
Software License Agreement

Passing the --accept-sla flag assumes the acceptance of the Magic Leap 2 Software License Agreement.

Verify Installation

Once the AR Cloud deployment completes, the deployment script will print out the cluster information similar to:

------------------------------
Cluster Installation (arcloud)
------------------------------

Enterprise Web:
--------------

http://<DOMAIN>/

Username: aradmin
Password: <base64-encoded string>

Keycloak:
---------

http://<DOMAIN>/auth/

Username: admin
Password: <base64-encoded string>

MinIO:
------

kubectl -n arcloud port-forward svc/minio 8082:81
http://127.0.0.1:8082/

Username: <base64-encoded string>
Password: <base64-encoded string>

PostgreSQL:
------

kubectl -n arcloud port-forward svc/postgresql 5432:5432
psql -h 127.0.0.1 -p 5432 -U postgres -W

Username: postgres
Password: <base64-encoded string>

Network:
--------
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istio-system istio-ingressgateway LoadBalancer <IPv4> <IPv4> 80:31456/TCP,443:32737/TCP,15021:31254/TCP,1883:30231/TCP,8883:32740/TCP 1d

Log in to the Enterprise Console

  1. Open the Enterprise Console URL (http://<DOMAIN>/) in a browser
  2. Enter the credentials for Enterprise Web provided by the deployment script
  3. Verify the successful login

Register an ML2 device

Web console

Perform the following steps using the web-based console:

  1. Log in to the Enterprise Console
  2. Select Devices from the top menu
  3. Click Configure to display a QR code unique for your AR Cloud instance

ML2 device

Perform the following steps from within your ML2 device:

  1. Open the Settings app
  2. Select Perception
  3. Select the QR code icon next to AR Cloud
  4. Scan the QR code displayed in the web console
  5. Wait for the process to finish and click on the Login button
  6. Enter the user account credentials in the ML2 device web browser

The Enterprise Console should show the registered device on the list.