plgd on K8S
In this section, you can find several examples of how to deploy plgd hub with external OAuth2.0 Server or with mocked one for development purposes.
Getting started
In our GitHub repository you can find charts/
folder with plgd hub Helm chart. This chart is automatically published to the Helm registry https://charts.plgd.dev
during the release. Version of the chart is in sync with the appversion, matching the release tag (e.g. 2.1.1). All configuration values are documented here.
Install Certificate Manager
A communication between devices, clients and plgd hub is secured as well as between plgd hub services. To simplify the deployment and certificate management, Certificate Manager, required dependency, have to be deployed in your Kubernetes cluster.
> kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.6.0/cert-manager.yaml
Register plgd Helm Chart Registry
> helm repo add plgd https://charts.plgd.dev
> helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "plgd" chart repository
> helm repo list
NAME URL
plgd https://charts.plgd.dev
> helm search repo plgd
NAME CHART VERSION APP VERSION DESCRIPTION
plgd/plgd-hub 2.1.1 2.1.1 A Helm chart for plgd-hub
Deployment with Mock OAuth2.0 Server
Quickest way how to install your own instance of the plgd hub is to use the Mock OAuth2.0 Server. With this option enabled, no authentication is available. The JWT token is automatically issued for the default user.
> echo "global:
domain: \"example.com\"
hubId: \"d03a1bb4-0a77-428c-b78c-1c46efe6a38e\"
mockoauthserver:
enabled: true" > withMock.yaml
> helm install -f withMock.yaml hub plgd/plgd-hub
Deployment of the plgd hub to the Kubernetes cluster is then initiated. Status of the deployment can be verified by calling kubectl get all
. When all pods are up and running, the plgd Dasboard will become available on your configured domain (e.g. https://example.com
).
NodePort for CoAP Gateway
In case you install plgd hub into microk8s.io/, it’s required to enable also
nodePort for the CoAP Gateway Service and extend the port range of the K8S API Server. To extend the port range, add --service-node-port-range=5683-32767
to /var/snap/microk8s/current/args/kube-apiserver
. For the CoAP Gateway Service, apply following values:
coapgateway:
service:
type: NodePort
nodePort: 5684
Deployment with Auth0 OAuth2.0 Server
Our try.plgd.cloud instance which is available for free uses Auth0 Identity Provider. Example configuration enabling an integration with an external OAuth2.0 Server should contain OAuth2.0 configuration for the device as well as the dasboard. All required values are part of the global.
index.
> echo "global:
domain: \"example.com\"
hubId: \"d03a1bb4-0a77-428c-b78c-1c46efe6a38e\"
authority: \"https://myinstance.auth0.com\"
audience: \"https://api.example.com\"
oauth:
device:
- name: \"onboardingtool.mobile\"
clientID: \"l12j3oi12j3jlk1904\"
clientSecret: \"891y2ehpu2he9182heh2ep9128eh\"
scopes: [\"offline_access\"]
redirectURL: \"com.example.mobile://login-callback\"
useInUi: false
- name: \"onboardingtool.desktop\"
clientID: \"i0jt0i00xcva0r\"
clientSecret: \"98219h23uh43t9r4h93rh994th923r\"
scopes: [\"offline_access\"]
redirectURL: \"https://example.com/things\"
useInUi: true
web:
clientID: \"98y239hu94hr2ohu3e23eh\"" > withMock.yaml
> helm install -f withMock.yaml hub plgd/plgd-hub
Using Let’s encrypt certificates
By default, the plgd hub Helm chart issues a self-signed CA certificate, used to sign domain certificates of all exposed services. To encrypt the external communication with the certificates signed by the Let’s Encrypt CAs, create an issuer:
> echo "apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: \"letsencrypt-prod\"
spec:
acme:
server: \"https://acme-v02.api.letsencrypt.org/directory\"
email: \"info@example.com\"
privateKeySecretRef:
name: \"letsencrypt-prod\"
solvers:
- http01:
ingress:
class: public" > issuer.yaml
> kubectl apply -f issuer.yaml
Required values for the plgd hub Helm chart which makes use of a newly created signer are:
certmanager:
external:
issuer:
kind: "ClusterIssuer"
name: "letsencrypt-prod"
global:
enableWildCartCert: false
...
Troubleshooting
- plgd Dashboard returns “unable to fetch data from from the ./well-known endpoint” error
- Not trusted self-signed certificate is used. Import of plgd CA to your system is required. Get the public key by calling
kubectl get secret plgd-ca -o 'go-template={{index .data "ca.crt"}}' | base64 -d
.
- Not trusted self-signed certificate is used. Import of plgd CA to your system is required. Get the public key by calling