README.md

provider-natssecretssecrets

provider-natssecretssecrets is a Crossplane Provider that implements EdgeFarm's Vault Nats Secrets Plugin as managed resources.

Features

The provider supports the following resources:

• Operators
• Accounts
• Users
• Operator signing keys
• Account signing keys

🎯 Installation

Make sure you have Crossplane installed. See the Crossplane installation guide

Create a Provider resource:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-natssecrets
spec:
  package: ghcr.io/edgefarm/provider-natssecrets/provider-natssecrets:master
  packagePullPolicy: IfNotPresent
  revisionActivationPolicy: Automatic
  revisionHistoryLimit: 1

NOTE: Instead of using package version master have a look at the available versions

📖 Examples

You might find the examples directory helpful. Every example in this directory is deployable in a make dev environment.

For a full spec of possible options

• go to docs.crds.dev for Operator, Account, User, AccountSigningKey and OperatorSigningKey
• use the kubectl explain command

# How to use kubectl explain
$ kubectl explain operator.spec.forProvider
$ kubectl explain account.spec.forProvider
$ kubectl explain user.spec.forProvider
$ kubectl explain accountsigningkey.spec.forProvider
$ kubectl explain operatorsigningkey.spec.forProvider

Examples of operator, account and user resources

Example operator resource

apiVersion: issue.natssecrets.crossplane.io/v1alpha1
kind: Operator
metadata:
  name: myoperator
spec:
  forProvider:
    syncAccountServer: true
    createSystemAccount: true
    claims:
      operator:
        accountServerUrl: "nats://nats.nats:4222"
        signingKeys:
          - opsk1
        strictSigningKeyUsage: false
  providerConfigRef:
    name: vault-creds
  writeConnectionSecretToRef:
    namespace: crossplane-system
    name: myoperator

Example sys account resource

apiVersion: issue.natssecrets.crossplane.io/v1alpha1
kind: Account
metadata:
  name: sys
spec:
  forProvider:
    operator: myoperator
    useSigningKey: opsk1
    claims:
      account:
        signingKeys:
          - sask1
        limits:
          subs: -1
          conn: -1
          leafNodeConn: -1
          data: -1
          payload: -1
          wildcardExports: true
          imports: -1
          exports: -1
        exports:
          - name: account-monitoring-streams
            subject: "$SYS.ACCOUNT.*.>"
            type: Stream
            accountTokenPosition: 3
            description: Account specific monitoring stream
            infoURL: https://docs.nats.io/nats-server/configuration/sys_accounts
          - name: account-monitoring-services
            subject: "$SYS.ACCOUNT.*.*"
            type: Service
            responseType: Stream
            accountTokenPosition: 4
            description:
              "Request account specific monitoring services for: SUBSZ, CONNZ,
              LEAFZ, JSZ and INFO"
            infoURL: https://docs.nats.io/nats-server/configuration/sys_accounts
  providerConfigRef:
    name: vault-creds
  writeConnectionSecretToRef:
    namespace: crossplane-system
    name: sys

Example default sys account user resource

apiVersion: issue.natssecrets.crossplane.io/v1alpha1
kind: User
metadata:
  name: default-push
spec:
  forProvider:
    operator: myoperator
    account: sys
    useSigningKey: sask1
    claims:
      user:
        data: -1
        payload: -1
        subs: -1
        pub:
          allow:
            - "$SYS.REQ.CLAIMS.LIST"
            - "$SYS.REQ.CLAIMS.UPDATE"
            - "$SYS.REQ.CLAIMS.DELETE"
        resp:
        sub:
          allow:
            - _INBOX.>
  providerConfigRef:
    name: vault-creds

Example standard account resource

apiVersion: issue.natssecrets.crossplane.io/v1alpha1
kind: Account
metadata:
  name: myaccount
spec:
  forProvider:
    operator: myoperator
    claims:
      account:
        defaultPermissions:
          pub:
            allow:
              - foo
              - bar
        limits:
          subs: -1
          conn: -1
          leafNodeConn: -1
          data: -1
          payload: -1
          wildcardExports: true
          imports: -1
          exports: -1
  providerConfigRef:
    name: vault-creds
  writeConnectionSecretToRef:
    namespace: crossplane-system
    name: myaccount

Example user resource

apiVersion: issue.natssecrets.crossplane.io/v1alpha1
kind: User
metadata:
  name: myuser
spec:
  forProvider:
    operator: myoperator
    account: myaccount
    claims:
      user:
        data: 100
        payload: 200
        subs: 300
        pub:
          allow:
            - foo
  providerConfigRef:
    name: vault-creds
  writeConnectionSecretToRef:
    namespace: crossplane-system
    name: myuser

Signing keys

Signing keys can be either generated by the provider or imported from an existing secret. The secret must contain the base64 encoded nkey seed.

Example of an `OperatorSigningKey` resource importing a secret

apiVersion: nkey.natssecrets.crossplane.io/v1alpha1
kind: OperatorSigningKey
metadata:
  name: opsk1
spec:
  forProvider:
    operator: myoperator
    config:
      import:
        secretRef:
          name: opsk1
          namespace: default
          key: seed
  providerConfigRef:
    name: vault-creds
---
apiVersion: v1
kind: Secret
metadata:
  name: opsk1
  namespace: default
data:
  # base64 encoded operator nkey seed
  seed: U09BT0dMWFpDUzVUU1ZTTVBMM01QUjYzM0JaQUI2VkNJS1FJM1RMVTRaNUxFRlZEM0syRVQ1TUtQVQo=

Example of an `AccountSigningKey` without importing a secret

apiVersion: nkey.natssecrets.crossplane.io/v1alpha1
kind: AccountSigningKey
metadata:
  name: mykey1
spec:
  forProvider:
    operator: myoperator
    account: myaccount
  providerConfigRef:
    name: vault-creds

🐞 Debugging

Just start the debugger of your choice to debug cmd/provider/main.go. The only thing that is important is, that your KUBECONFIG points to a dev cluster with the CRDs deployed (see Developing locally).

🧪 Test environment

To test the provider locally, you can use devspace to spin up a local kind cluster with the following components installed:

• Hashicorp Vault (with custom TLS certificate)
• NATS Server
• Crossplane
• provider-natssecrets (this project)

To start the test environment, run the following command:

$ devspace run create-kind-cluster
$ devspace run-pipeline init
$ devspace run-pipeline deploy-vault
$ devspace run-pipeline deploy-crossplane
$ devspace run-pipeline deploy-nats

Once the environment is up and running you can use the nats cli to connect to the NATS server and publish messages with user credentials.

# Create the account and user and get the creds for the user
$ devspace run-pipeline create-custom-nats-account
$ kubectl port-forward -n nats svc/nats 4222:4222 &
$ PID=$!

# Publish and subscribe using the creds previously fetched
$ docker run -it -d --name nats-subscribe --network host -v $(pwd)/.devspace/creds/creds:/creds natsio/nats-box:0.13.4 nats sub -s nats://localhost:4222 --creds /creds foo 
$ docker run --rm -d -it --name nats-publish --network host -v $(pwd)/.devspace/creds/creds:/creds natsio/nats-box:0.13.4 nats pub -s nats://localhost:4222 --creds /creds foo --count 3 "Message {{Count}} @ {{Time}}"

# Log output shows that authenticating with the creds file works for pub and sub
$ docker logs nats-subscribe
14:49:35 Subscribing on foo 
[#1] Received on "foo"
Message 1 @ 2:49PM

[#2] Received on "foo"
Message 2 @ 2:49PM

[#3] Received on "foo"
Message 3 @ 2:49PM

# Cleanup
$ docker kill nats-subscribe
$ docker rm nats-subscribe
$ pkill $PID

🤝🏽 Contributing

Code contributions are very much welcome.

1. Fork the Project
2. Create your Branch (git checkout -b AmazingFeature)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature")
4. Push to the Branch (git push origin AmazingFeature)
5. Open a Pull Request targetting the beta branch.