doc: Add interop deployment documentation (TheThingsIndustries#649)

michalborkowski96 · web-flow · commit a7d3e2053ddb · 2021-11-10T09:20:37.000+01:00
doc: Add interop deployment documentation
diff --git a/doc/content/getting-started/aws/ecs/interop/_index.md b/doc/content/getting-started/aws/ecs/interop/_index.md
@@ -0,0 +1,67 @@
+---
+title: "Interoperability"
+description: "LoRaWAN Backend Interfaces"
+weight: 3
+---
+
+{{% tts %}} exposes the Join Server API defined by LoRaWAN Backend Interfaces 1.0 and 1.1. This is used for interoperability between LoRaWAN networks. The functionality can be exposed either by the Join Server or by the Identity Server, but not both at once.
+
+Join Server is capable of handling the join flow, that is `HomeNSReq`, `JoinReq` and `AppSKeyReq` requests. Identity Server can only answer to `HomeNSReq`. Typically, you should enable interoperability if you want to use device activations through Packet Broker. You can use Join Server interoperability if you want to expose the entire join flow to other LoRaWAN network servers.
+
+# Join Server interoperability
+
+## Deployment
+
+### Step 1: deploy {{% tts %}}
+
+Deploy {{% tts %}} normally. For the `PeerRequesterAccountId` parameter in `1-1-vpc`, use the ID of the account where you want to deploy Crypto Server. Do not enable interop and assume that {{% tts %}} doesn't connect to the Crypto Server.
+
+### Step 2: add certificates
+
+For the server certificate, use the certbot task. It will request a certificate and put it into AWS Secrets Manager. If you do not want to use the certbot task, but prefer to provide your own certificate, look up the relevant secret created in template `4-1-secrets` and substitute the dummy value. Certificates are expected to be in PEM format.
+
+Client certificates are stored in the interop config bucket, created in template `2-4b-routing-s3`. In this bucket you need to place a file `config.yml`, which contains a map `<net-id>: <ca.pem>`. Example configuration:
+
+```yaml
+000000: ca-000000.pem
+000009: ca-000009.pem
+```
+
+### Step 3: deploy the Crypto Server
+
+Deploy the template `200-1-crypto`. This template is designed to be deployed in a separate account, but same region. No other templates are needed for Crypto Server, this is a self-contained deployment.
+
+- the tuple `{NetworkName}.${Environment}.${Cluster}` should NOT be identical. We suggest using the same `NetworkName` and `Environment`, but different `Cluster`
+- the `CidrBlock` parameter should NOT be identical
+- the `ClusterSecretValue` parameter MUST be identical
+- the `DefaultTenantID` parameter MUST be identical
+- the `Domain` parameter MUST be identical
+- skip the `ServicesDNSZone` parameter
+- refer to outputs of the `1-1-vpc` template for the `Peer*` parameters
+
+### Step 4: peer networks
+
+Deploy the template `6-1-vpc-peering` where you had deployed the Join Server to create the peering association. Refer to the Crypto Server stack for inputs of `6-1-vpc-peering`.
+
+{{% tts %}} uses Route53 for service discovery. In order to enable the Join Server <-> Crypto Server service discovery, you need to associate the `${NetworkName}.${Environment}.${Cluster}.cluster.local` hosted zone of Join Server with the VPC of Crypto Server and vice versa. For details on how to do it, refer to the [AWS Documentation](https://aws.amazon.com/premiumsupport/knowledge-center/route53-private-hosted-zone/).
+
+### Step 5: activate the connection
+
+Go through the Join Server stack and turn on switches for Interop and Crypto Server connection. The `CryptoServerDNSName` parameter in template `5-4-services` is expected to be in format `cs.${NetworkName}.${Environment}.${Cluster}.cluster.local`.
+
+Go through the Crypto Server template and turn on switches for Join Server connection. The `ServicesDNSZone` parameter is expected to be in format `${NetworkName}.${Environment}.${Cluster}.cluster.local`.
+
+### Step 6: encrypt key values for secure element parts
+
+Go to the Crypto Server stack and encrypt secure element parts keys using the AWS KMS key from stack output `MicrochipPartsTableKey` and put them into the DynamoDB table from output `MicrochipPartsTable`. You can do it in the following way:
+1. Create a file `input.json` with the following contents: `{"KeyId": "<MicrochipPartsTableKey>", "Plaintext": "<SecureElementKeyValueInBase64>"}`
+2. `aws kms encrypt --cli-input-json file://input.json`. It is important to use the input json file so that secret value doesn't stay in history
+3. Change the contents of `input.json` to `{"TableName": "<MicrochipPartsTableKey>", "Item": {"part_number": {"S": "<PartNumber>"}, "psk_root_keys_encrypted": {"S": "<CiphertextBlobFromKMSEncrypt>"}}}`
+4. `aws dynamodb put-item --cli-input-json file://input.json`
+5. `rm input.json`
+
+At this point interoperability should be working. It might be required to restart the containers before they pick up new configuration.
+
+# Identity Server interoperability
+
+Identity Server interoperability doesn't need Crypto Server, therefore you don't need to set up two accounts and peer networks. Still, you need to set up TLS certificates in a similar fashion.
