[DOCS] Document the use of environment variables that may be too sensitive to be kept in YAML

[omerbensaadon]

A possible workaround: It appears that the client run-examples command accepts some parameters:

$ cloud-service-broker client run-examples --help
Run all examples generated by the use command through a
        provision/bind/unbind/deprovision cycle.

        Exits with a 0 if all examples were successful, 1 otherwise.

Usage:
  cloud-service-broker client run-examples [flags]

Flags:
      --example-name string   only run examples matching this name
      --filename string       json file that contains list of CompleteServiceExamples
  -h, --help                  help for run-examples
  -j, --jobs int              number of parallel client examples to run concurrently (default 1)
      --service-name string   name of the service to run tests for

Global Flags:
      --config string   Configuration file to be read

I suspect I can supply the test parameters using the --filename parameter, although there's no documentation about this option or what a CompleteServiceExamples might be. (I am guessing it is expecting a YAML block that corresponds to the examples block in the service YAML; will report back.)

This needs documentation!

_Originally posted by @mogul in https://github.com/pivotal/cloud-service-broker/issue_comments/708887286_

[mogul]

In the absence of these docs I'm trying to figure out how to use run-examples with --filename and haven't been successful...

My examples.json file looks like:

[
    {
       "name": "Operator in local k8s",
       "description": "Provision a SolrCloud operator in a local k8s",
       "service_name": "solr-operator",
       "service_id": "f145c5aa-4cee-4570-8a95-9a65f0d8d9da",
       "plan_id": "1779d7d5-874a-4352-b9c4-877be1f0745b",
       "provision_params": {
          "namespace": "default",
          "server": "https://kubernetes.docker.internal:6443",
          "cluster_ca_certificate": "YOUR_CERT",
          "token": "YOUR_TOKEN",
          "ingress_base_domain": "ing.local.domain"
       },
       "bind_params": {}
    },
    {
       "name": "Cloud in local k8s",
       "description": "Provision a SolrCloud instance in a local k8s",
       "service_name": "solr-cloud",
       "service_id": "b9013a91-9ce8-4c18-8035-a135a8cd6ff9",
       "plan_id": "e35e9675-413f-4f42-83de-ad5003357e77",
       "provision_params": {
          "namespace": "default",
          "server": "https://kubernetes.docker.internal:6443",
          "cluster_ca_certificate": "YOUR_CERT",
          "token": "YOUR_TOKEN",
          "ingress_base_domain": "ing.local.domain",
          "cloud_name": "example"
       },
       "bind_params": {}
    }
 ]

When I execute the command cloud-service-broker client run-examples --filename examples.json I get:

2020/10/16 17:05:24 Running Example: /Operator in local k8s
2020/10/16 17:05:24 cloud-service-broker client provision --instanceid "ex708449921-" --planid "1779d7d5-874a-4352-b9c4-877be1f0745b" --serviceid "" --params "[REDACTED]"
2020/10/16 17:05:24 cloud-service-broker client bind --instanceid "ex708449921-" --planid "1779d7d5-874a-4352-b9c4-877be1f0745b" --serviceid "" --bindingid "ex708449921" --params "{}"
2020/10/16 17:05:24 cloud-service-broker client unbind --instanceid "ex708449921-" --planid "1779d7d5-874a-4352-b9c4-877be1f0745b" --serviceid "" --bindingid "ex708449921"
2020/10/16 17:05:24 cloud-service-broker client deprovision --instanceid "ex708449921-" --planid "1779d7d5-874a-4352-b9c4-877be1f0745b" --serviceid ""
2020/10/16 17:05:24 Provisioning /Operator in local k8s
2020/10/16 17:05:24 PUT http://user:pass@broker:80/v2/service_instances/ex708449921-?accepts_incomplete=true -> 400, "{\"description\":\"service_id missing\"}\n"
2020/10/16 17:05:24 Cleaning up the environment
2020/10/16 17:05:24 Unbinding /Operator in local k8s
2020/10/16 17:05:24 DELETE http://user:pass@broker:80/v2/service_instances/ex708449921-/service_bindings/ex708449921?service_id=&plan_id=1779d7d5-874a-4352-b9c4-877be1f0745b -> 400, "{\"description\":\"service_id missing\"}\n"
2020/10/16 17:05:24 Deprovisioning /Operator in local k8s
2020/10/16 17:05:24 DELETE http://user:pass@broker:80/v2/service_instances/ex708449921-?accepts_incomplete=true&service_id=&plan_id=1779d7d5-874a-4352-b9c4-877be1f0745b -> 400, "{\"description\":\"service_id missing\"}\n"
2020/10/16 17:05:24 Error executing examples from file: Unexpected response code 400
make: *** [test] Error 1

You can see it's generating --serviceid "" in the output above. This is after I tried adding both service_name: and service_id: to the examples.json file; it seems to be ignoring those.

I haven't looked at the broker code yet to figure out what the broker is expecting. Any ideas?

[mogul]

I haven't looked at the broker code yet to figure out what the broker is expecting.

Here's a clue, from a file that's no longer in the repository: https://github.com/pivotal/cloud-service-broker/blob/efb72c7f76e58a099e547476ce47acd9a60a951b/pkg/client/complete-service-examples-testfile.json#L8-L9

The JSON annotations here should result in those values also being populated from service_id and service_name but clearly that's not working... More digging needed!

[erniebilling]

This isn't really what the examples section of the brokerpak were built for. To test situations that require sensitive information (especially that will be unique to your environment) we suggest using the cloud-service-broker client provision and cloud-service-broker client bind commands with the --params option to pass in unique/sensitive data.

[mogul]

We inspected the source and finally figured out what the JSON for the --filename parameter should look like. Here's an example: https://github.com/GSA/datagov-brokerpak/blob/solr-cloud/examples.json-template

[erniebilling]

Did this solve your problem @mogul ?

[mogul]

Yes it did! I do suggest documenting it.