The AMRC Connectivity Stack (ACS) is a Kubernetes Helm chart that contains a comprehensive set of open-source services developed by the AMRC that enables an end-to-end implementation of the Factory+ framework.
Ensure that you familiarise yourself with the concepts of both Kubernetes and Factory+ before continuing. This chart installs a full end-to-end deployment of Factory+ onto a Kubernetes cluster and there are a lot of moving parts.
Although Factory+ and ACS fully supports edge-based Cell Gateways, this chart does not support the deployment of edge-based Cell Gateways located on other Kubernetes Clusters, which is recommended in production. This is due to the fact that the chart deploys manifests to Cell Gateways, which requires the nodes to be on the same cluster. We already have a proof-of-concept implementation of how to address this and we aim to update this Helm chart in the near future to support.
This chart can be installed onto a local Kubernetes cluster for development or testing by following the instructions below. For production deployments, please refer to the production deployment guide.
Helm is a package manager for Kubernetes that allows you to easily install and manage applications on Kubernetes. It must be installed on the machine that you’ll be using to deploy ACS from. To install Helm, follow the instructions here.
Kubectl is a command-line tool for controlling Kubernetes clusters. It must be installed on the machine that you’ll be using to deploy ACS from. To install Kubectl, follow the instructions here.
Minikube is a tool that allows you to run a local Kubernetes cluster on your machine. It is not required to deploy ACS, but it is recommended for development and testing. To install Minikube, follow the instructions here. If you do not wish to use Minikube, you can deploy ACS to any Kubernetes cluster.
To verify that Helm and Kubectl have been installed correctly, run the following commands:
helm version
kubectl version
minikube version
Next, create a new MiniKube cluster by running the following command:
minikube start
To verify that you can connect to your MiniKube cluster, run the following command:
kubectl cluster-info
This Chart creates a load balancer on your Kubernetes cluster that exposes all services at various subdomain. Please ensure that you have a wildcard DNS entry configured to direct all *.<baseURL> requests to your local kube cluster. For example, if you set baseUrl to localhost, you should have a DNS entry that directs all *.localhost requests to your local kube cluster on ports 80 and/or 443 (depending on whether you have enabled secure and want to serve ACS over HTTPS).
Now it’s time to install the AMRC Connectivity Stack. It’s recommended that you utilise a tool like Lens to view the cluster status as it bootstraps to ensure that everything is working as expected. Lens can be downloaded here.
First, add the AMRC Factory+ Helm repository:
helm repo add amrc-connectivity-stack https://amrc-factoryplus.github.io/amrc-connectivity-stack/build
helm repo update
Next, create a values.yaml file in a sensible location on your local machine. This file will be used to configure the deployment and can contain many options for customisation and configuration (see values for more information). At the very least, you should set the following values:
acs:
baseUrl: localhost # Set this to the domain that ACS will be served from. Localhost should suffice for development.
organisation: AMRC # Set this to the name of your organisation. It will be used across the deployment for branding and naming.
secure: false # Set this to true if you want to serve ACS over HTTPS. This is recommended for production deployments but can be turned for development.
tlsSecretName: factoryplus-tls # Set this to the name of the secret containing the wildcard certificate for the above domain. This is only required if secure is set to true.
identity:
realm: LOCALHOST # Set the identity realm for the deployment. This is used to namespace the identity server and should be unique to your deployment. It is recommended that you use the domain name in capitals for this value.
Before we install, we need to create the factory-plus namespace, which is where all ACS services will be deployed to. If a different namespace is chosen by changing the -n <namespace> on the helm install command then ensure the namespace exists before installing ACS.
To create the factory-plus namespace, run the following command:
kubectl create namespace factory-plus
Finally, install ACS by running the following command.
helm install acs amrc-connectivity-stack/amrc-connectivity-stack -f values.yaml --namespace factory-plus
Alternatively, the values can be supplied directly to the helm install command:
helm install acs amrc-connectivity-stack/amrc-connectivity-stack --set acs.baseUrl=localhost --set acs.organisation=AMRC --set acs.secure=false --namespace factory-plus
If all went to plan you should now have a fully functioning ACS deployment beginning to deploy to your local Kubernetes cluster. Note that it can take a few minutes to have all services operational.
Take note of the service URLs printed at the end of the installation. You will need these to connect to the various services.
Get the password for the admin user by running the following command. Note that it may not return the password until the deployment has finished bootstrapping.
echo $(sudo kubectl get secret krb5-passwords -o jsonpath="{.data.admin}" -n | base64 --decode)
Once you have the admin password you can connect to the MQTT broker at the URL supplied to you and subscribe to spBv1.0/#. It’s advisable to do this before you start adding devices to the system so that you can see all traffic. MQTTExplorer is a good tool for this and can be downloaded here, however building the tool from this pull request may be more useful when working with ACS and Sparkplug messages.
Next, log into the manager at the URL supplied to you as the admin user and create a Group, Node (Soft Gateway) and Device. Configure the device by completing the Information, Connection, and Schema tabs until you see a green VALID tag in the top right corner. Once you’ve configured the device you should see MQTT traffic begin to flow.
Finally, get the admin password for InfluxDB by running the following command and log into the InfluxDB instance as the admin user at at the URL supplied to you.
echo $(sudo kubectl get secret acs-influxdb2-auth -o jsonpath="{.data.admin-password}" -n | base64 --decode)
Production deployment does not differ greatly from development deployment, however there are a few things to note:
baseUrlsecure is set to trueadmin user for disaster recovery| Name | |
|---|---|
| Alex Godbehere | alex.godbehere@amrc.co.uk |
| Ben Morrow | b.morrow@amrc.co.uk |
| Repository | Name | Version |
|---|---|---|
| https://alexgodbehere.github.io/helm-repository | operator | 5.0.4 |
| https://bitnami-labs.github.io/sealed-secrets/ | sealed-secrets | 2.8.1 |
| https://grafana.github.io/helm-charts | grafana | 6.52.4 |
| https://grafana.github.io/helm-charts | loki | 4.8.0 |
| https://grafana.github.io/helm-charts | promtail | 6.9.3 |
| https://helm.influxdata.com/ | influxdb2 | 2.1.1 |
| https://helm.traefik.io/traefik | traefik | 10.19.* |
| https://operator.min.io | tenant | 5.0.3 |
| Key | Type | Default | Description |
|——————————————-|——–|———————————|———————————————————————————————————————————————————————————————|
| acs.baseUrl | string | "localhost" | The base URL that services will be served from |
| acs.organisation | string | "AMRC" | The organisation where ACS is being deployed |
| acs.secure | bool | true | Whether or not services should be served over HTTPS |
| acs.tlsSecretName | string | "factoryplus-tls" | The name of the secret holding the wildcard certificate for the above domain. |
| auth.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Authorisation component |
| auth.image.repository | string | "acs-auth" | The repository of the Authorisation component |
| auth.image.tag | string | "latest" | The tag of the Authorisation component |
| cmdesc.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Commands component |
| cmdesc.image.repository | string | "acs-cmdesc" | The repository of the Commands component |
| cmdesc.image.tag | string | "latest" | The tag of the Commands component |
| cmdesc.verbosity | int | 1 | Possible values are either 1 to enable all possible debugging, or a comma-separated list of debug tags (the tags printed before the log lines). No logging is specified as an empty string. |
| configdb.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Configuration Store component |
| configdb.image.repository | string | "acs-configdb" | The repository of the Configuration Store component |
| configdb.image.tag | string | "latest" | The tag of the Configuration Store component |
| directory.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Directory component |
| directory.image.repository | string | "acs-directory" | The repository of the Directory component |
| directory.image.tag | string | "latest" | The tag of the Directory component |
| identity.identity.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Identity component |
| identity.identity.image.repository | string | "acs-identity" | The repository of the Identity component |
| identity.identity.image.tag | string | "latest" | The tag of the Identity component |
| identity.krbKeysOperator.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the KerberosKey Operator |
| identity.krbKeysOperator.image.repository | string | "acs-krb-keys-operator" | The repository of the KerberosKey Operator |
| identity.krbKeysOperator.image.tag | string | "latest" | The tag of the KerberosKey Operator |
| identity.realm | string | "LOCALHOST" | The Kerberos realm for this Factory+ deployment. |
| manager.debug | bool | false | Whether debug mode is enabled. DO NOT USE THIS IN PRODUCTION. |
| manager.edge.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Edge Agent component |
| manager.edge.repository | string | "acs-edge" | The repository of the Edge Agent component |
| manager.edge.tag | string | "latest" | The tag of the Edge Agent component |
| manager.env | string | "production" | The environment that the manager is running in |
| manager.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Manager component |
| manager.image.repository | string | "acs-manager" | The repository of the Manager component |
| manager.image.tag | string | "latest" | The tag of the Manager component |
| manager.logLevel | string | "warning" | The minimum log level that the manager will log messages at |
| manager.meilisearch.key | string | "masterKey" | The key that the manager uses to connect to the Meilisearch search engine |
| manager.name | string | "Factory+ Manager" | A string used to customise the branding of the manager |
| minio.exposeConsole | bool | false | Whether or not to expose the MinIO console outside of the cluster |
| mqtt.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the MQTT component |
| mqtt.image.repository | string | "acs-mqtt" | The repository of the MQTT component |
| mqtt.image.tag | string | "latest" | The tag of the MQTT component |
| warehouse.ingester.image.registry | string | "ghcr.io/amrc-factoryplus" | The registry of the Commands component |
| warehouse.ingester.image.repository | string | "influxdb-sparkplug-ingester" | The repository of the Commands component |
| warehouse.ingester.image.tag | string | "latest" | The tag of the Commands component |
———————————————-