Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update device provisioning service documentation #165

Merged
merged 4 commits into from
Sep 25, 2024
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/en/docs/configuration/certificate-authority.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ gRPC API of the Certificate Authority service as defined [here](https://github.c
| `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### HTTP API

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/cloud2cloud-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ A configuration template is available in [cloud2cloud-gateway/config.yaml](https
| `apis.http.authorization.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.http.authorization.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.http.authorization.http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.http.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### Event Bus

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/coap-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ OAuth2.0 Client is used to issuing an authorization code used by the Onboarding
| `apis.coap.authorization.providers[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.coap.authorization.providers[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.coap.authorization.providers[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.coap.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

{{< tip >}}

Expand Down
45 changes: 17 additions & 28 deletions content/en/docs/configuration/device-provisioning-service.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@ The Device Provisioning Service provides API to provision device to the [plgd/hu
Before you use the image you need to setup [K8s access to private registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry).

```bash
docker pull ghcr.io/plgd-dev/device-provisioning-service/device-provisioning-service:latest
docker pull ghcr.io/plgd-dev/hub/device-provisioning-service:latest
Danielius1922 marked this conversation as resolved.
Show resolved Hide resolved
```

## YAML Configuration

A configuration template is available on [config.yaml](https://github.com/plgd-dev/device-provisioning-service/blob/main/config.yaml).
A configuration template is available on [config.yaml](https://github.com/plgd-dev/hub/blob/main/device-provisioning-service/config.yaml).

### Logging

Expand All @@ -38,7 +38,7 @@ CoAP API as specified in the [workflow](./workflow.puml).

| Property | Type | Description | Default |
| ---------- | -------- | -------------- | ------- |
| `apis.coap.address` | string | `Listen specification <host>:<port> for coap client connection.` | `"0.0.0.0:5688"` |
| `apis.coap.address` | string | `Listening specification <host>:<port> for coap client connection.` | `"0.0.0.0:15684"` |
| `apis.coap.protocols` | []string | `Protocol for coap connection. The supported values are: "tcp", "udp" .` | `["tcp"]` |
| `apis.coap.maxMessageSize` | int | `Max message size which can be sent/received via coap. i.e. 256*1024 = 262144 bytes.` | `262144` |
| `apis.coap.messagePoolSize` | int | `Defines the maximum preallocated messages in the pool for parse/create coap messages.` | `1000` |
Expand All @@ -50,27 +50,30 @@ CoAP API as specified in the [workflow](./workflow.puml).

### HTTP API

The plgd device provisioning service REST API is defined by [swagger](https://raw.githubusercontent.com/plgd-dev/device-provisioning-service/main/pb/service.swagger.json).
The plgd device provisioning service REST API is defined by [swagger](https://raw.githubusercontent.com/plgd-dev/hub/main/device-provisioning-service/pb/service.swagger.json).

| Property | Type | Description | Default |
| ---------- | -------- | -------------- | ------- |
| `apis.http.enabled` | bool | `Enable HTTP API.` | `false` |
| `apis.http.address` | string | `Listen specification <host>:<port> for http client connection.` | `"0.0.0.0:9100"` |
| `apis.http.address` | string | `Listening specification <host>:<port> for http client connection.` | `"0.0.0.0:9100"` |
| `apis.http.tls.caPool` | string | `File path to the root certificate in PEM format which might contain multiple certificates in a single file.` | `""` |
| `apis.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.http.tls.clientCertificateRequired` | bool | `If true, require client certificate.` | `true` |
| `apis.http.authorization.authority` | string | `Authority is the address of the token-issuing authentication server. Services will use this URI to find and retrieve the public key that can be used to validate the token’s signature.` | `""` |
| `apis.http.authorization.ownerClaim` | string | `Claim used to identify owner of the device.` | `"sub"` |
| `apis.http.authorization.audience` | string | `Identifier of the API configured in your OAuth provider.` | `""` |
| `apis.http.authorization.http.maxIdleConns` | int | `It controls the maximum number of idle (keep-alive) connections across all hosts. Zero means no limit.` | `16` |
| `apis.http.authorization.http.maxConnsPerHost` | int | `It optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block. Zero means no limit.` | `32` |
| `apis.http.authorization.http.maxIdleConnsPerHost` | int | `If non-zero, controls the maximum idle (keep-alive) connections to keep per-host. If zero, DefaultMaxIdleConnsPerHost is used.` | `16` |
| `apis.http.authorization.http.idleConnTimeout` | string | `The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. Zero means no limit.` | `30s` |
| `apis.http.authorization.http.timeout` | string | `A time limit for requests made by this Client. A Timeout of zero means no timeout.` | `10s` |
| `apis.http.authorization.http.tls.caPool` | string | `File path to the root certificate in PEM format which might contain multiple certificates in a single file.` | `""` |
| `apis.http.authorization.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.http.authorization.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.http.authorization.http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.http.authorization.endpoints[].authority` | string | `Authority is the address of the token-issuing authentication server. Services will use this URI to find and retrieve the public key that can be used to validate the token’s signature.` | `""` |
| `apis.http.authorization.endpoints[].http.maxIdleConns` | int | `It controls the maximum number of idle (keep-alive) connections across all hosts. Zero means no limit.` | `16` |
| `apis.http.authorization.endpoints[].http.maxConnsPerHost` | int | `It optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block. Zero means no limit.` | `32` |
| `apis.http.authorization.endpoints[].http.maxIdleConnsPerHost` | int | `If non-zero, controls the maximum idle (keep-alive) connections to keep per-host. If zero, DefaultMaxIdleConnsPerHost is used.` | `16` |
| `apis.http.authorization.endpoints[].http.idleConnTimeout` | string | `The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. Zero means no limit.` | `30s` |
| `apis.http.authorization.endpoints[].http.timeout` | string | `A time limit for requests made by this Client. A Timeout of zero means no timeout.` | `10s` |
| `apis.http.authorization.endpoints[].http.tls.caPool` | []string | `File paths to the root certificates in PEM format. The file may contain multiple certificates.` | `[]` |
| `apis.http.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.http.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.http.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.http.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |
| `apis.http.readTimeout` | string | `The maximum duration for reading the entire request, including the body by the server. A zero or negative value means there will be no timeout.` | `8s` |
| `apis.http.readHeaderTimeout` | string | `The amount of time allowed to read request headers by the server. If readHeaderTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout.` | `4s` |
| `apis.http.writeTimeout` | string | `The maximum duration before the server times out writing of the response. A zero or negative value means there will be no timeout.` | `16s` |
Expand Down Expand Up @@ -172,17 +175,3 @@ OAuth2.0 Client is used to obtain JWT with ownerClaim an deviceIDClaim via the c
You might have one client, but multiple APIs registered in the OAuth2.0 Server. What you might want to prevent is to be able to contact all the APIs of your system with one token. This audience allows you to request the token for a specific API. If you configure it to myplgdc2c.api in the Auth0, you have to set it here if you want to also validate it.

{{< /tip >}}

### Task Queue

| Property | Type | Description | Default |
| ---------- | -------- | -------------- | ------- |
| `taskQueue.goPoolSize` | int | `Maximum number of running goroutine instances.` | `1600` |
| `taskQueue.size` | int | `Size of queue. If it exhausted, submit returns error.` | `2097152` |
| `taskQueue.maxIdleTime` | string | `Sets up the interval time of cleaning up goroutines. Zero means never cleanup.` | `10m` |

{{< note >}}

Note that the string type related to time (i.e. timeout, idleConnTimeout, expirationTime) is decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".

{{< /note >}}
1 change: 1 addition & 0 deletions content/en/docs/configuration/grpc-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ gRPC API of the gRPC Gateway service as defined [here](https://github.com/plgd-d
| `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### Identity Store Client

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/http-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ APIs of the HTTP Gateway service as defined [uri](https://github.com/plgd-dev/hu
| `apis.http.authorization.http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.http.authorization.http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.http.authorization.http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.http.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### GRPC Gateway Client

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/identity-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ gRPC API of the Identity Store service as defined [here](https://github.com/plgd
| `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### Event Bus

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/resource-aggregate.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ gRPC API of the Resource Aggregate service as defined [here](https://github.com/
| `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### Event Bus

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/resource-directory.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ gRPC API of the Resource Directory service.
| `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### Event Bus

Expand Down
1 change: 1 addition & 0 deletions content/en/docs/configuration/snippet-service.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ gRPC API of the Snippet service as defined [here](https://github.com/plgd-dev/hu
| `apis.grpc.authorization.endpoints[].http.tls.keyFile` | string | `File path to private key in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.certFile` | string | `File path to certificate in PEM format.` | `""` |
| `apis.grpc.authorization.endpoints[].http.tls.useSystemCAPool` | bool | `If true, use system certification pool.` | `false` |
| `apis.grpc.authorization.tokenTrustVerification.cacheExpiration` | string | `Duration for which a valid token is kept in a runtime cache before re-verification is required.` | `30s` |

### HTTP API

Expand Down
1 change: 0 additions & 1 deletion content/en/docs/deployment/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ plgd https://charts.plgd.dev

// helm search repo plgd
NAME CHART VERSION APP VERSION DESCRIPTION
plgd/plgd-dps 0.9.0 0.9.0 A Helm chart for plgd device provisioning service
plgd/plgd-hub 2.7.15 2.7.15 A Helm chart for plgd-hub

```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The basic deployment uses Mock OAuth Server, so it shall be used only for test/d
Before deploying the Device Provisioning Service on Kubernetes, make sure to follow the steps in [Hub](/docs/deployment/device-provisioning-service/hub) first. Then apply the changes from this page to the configuration. Once done, you can deploy the hub with the Device Provisioning Service.
{{< /note >}}

For Device Provisioning Service, all configuration values are documented [here](https://github.com/plgd-dev/device-provisioning-service/blob/main/charts/device-provisioning-service/README.md#values).
For Device Provisioning Service, all configuration values are documented [here](https://github.com/plgd-dev/hub/blob/main/charts/plgd-hub/README.md#values). Look for values starting with `deviceProvisioningService`.

## Device provider for Device Provisioning Service

Expand Down Expand Up @@ -61,29 +61,6 @@ mockoauthserver:

For production, you need to set the OAuth server client credential flow, as is described in [Customize OAuth server client credential flow](/docs/deployment/device-provisioning-service/advanced).

{{< /warning >}}

To allow download the Device Provisioning Service docker image by k8s, the following configuration needs to extend the configuration:

```yaml
deviceProvisioningService:
image:
dockerConfigSecret: |
{
"auths": {
"ghcr.io": {
"auth": "<DOCKER_AUTH_TOKEN>"
}
}
}
```

{{< note >}}

To access ghcr.io, please reach out to us at [[email protected]](mailto:[email protected]) in order to request permission for your GitHub account to access the plgd device provisioning server images. You can refer to the [documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for instructions on how to allow access.

{{< /note >}}

## Configure Enrollment Groups

The enrollment groups can be configured via deployment, utilizing the setup from the hub configuration to populate the values.
Expand Down Expand Up @@ -155,14 +132,12 @@ To deploy the hub with the Device Provisioning Service, apply the following comm

```sh
helm upgrade -i -n plgd --create-namespace -f withMock.yaml hub plgd/plgd-hub
helm upgrade -i -n plgd --create-namespace -f withMock.yaml dps plgd/plgd-dps
```

You can execute these commands multiple times to update the configuration. In such cases, you will need to restart the pods by deleting them:

```sh
kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd")
kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "dps-plgd")
kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "plgd-hub")
```

## Final configuration with mock oauth server
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,12 @@ If you encounter issues with the Device Provisioning Service or Hub, follow thes

```sh
helm upgrade -i -n plgd --create-namespace -f ./withUpdatedMock.yaml hub plgd/plgd-hub
helm upgrade -i -n plgd --create-namespace -f ./withUpdatedMock.yaml dps plgd/plgd-dps
```

3. Restart the pods by deleting them:

```sh
kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "hub-plgd")
kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "dps-plgd")
kubectl -n plgd delete $(kubectl -n plgd get pods -o name | grep "plgd-hub")
```

These steps will enable debug logging and restart the necessary components, providing more detailed information for troubleshooting the issues with the Device Provisioning Service or Hub.
Expand All @@ -46,7 +44,7 @@ If your device is unable to connect to DPS, follow these steps:
1. Check the DPS logs by running the following command:

```sh
kubectl -n plgd logs $(kubectl -n plgd get pods -o name | grep "dps-plgd")
kubectl -n plgd logs $(kubectl -n plgd get pods -o name | grep "plgd-hub-device-provisioning-service")
```

2. Check the device logs in the console.
Expand Down
Loading
Loading