chore: Updated docs and added some test coverage

Signed-off-by: Steven Gettys <s.gettys@f5.com>

api/v1/parameterset_types_test.go

@@ -33,10 +33,15 @@ func TestParameterSetSpec_ToPorterDocument(t *testing.T) {
 			fields: fields{SchemaVersion: "1.0.1",
 				Name:      "porter-test-me",
 				Namespace: "dev",
-				Parameters: []Parameter{{
-					Name:   "param1",
-					Source: ParameterSource{Value: "test-param"},
-				},
+				Parameters: []Parameter{
+					{
+						Name:   "param1",
+						Source: ParameterSource{Value: "test-param"},
+					},
+					{
+						Name:   "param2",
+						Source: ParameterSource{Secret: "test-secret"},
+					},
 				},
 			},
 			wantFile:   wantGoldenFile,
@@ -56,7 +61,7 @@ func TestParameterSetSpec_ToPorterDocument(t *testing.T) {
 			got, err := cs.ToPorterDocument()
 			if tt.wantErrMsg == "" {
 				require.NoError(t, err)
-				portertest.CompareGoldenFile(t, "testdata/parameter-set.yaml", string(got))
+				portertest.CompareGoldenFile(t, tt.wantFile, string(got))
 			} else {
 				portertests.RequireErrorContains(t, err, tt.wantErrMsg)
 			}
@@ -92,14 +97,14 @@ func TestParameterSet_SetRetryAnnotation(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			cs := &ParameterSet{
+			ps := &ParameterSet{
 				TypeMeta:   tt.fields.TypeMeta,
 				ObjectMeta: tt.fields.ObjectMeta,
 				Spec:       tt.fields.Spec,
 				Status:     tt.fields.Status,
 			}
-			cs.SetRetryAnnotation(tt.args.retry)
-			assert.Equal(t, tt.args.retry, cs.Annotations[AnnotationRetry])
+			ps.SetRetryAnnotation(tt.args.retry)
+			assert.Equal(t, tt.args.retry, ps.Annotations[AnnotationRetry])
 		})
 	}
 }

api/v1/testdata/parameter-set.yaml

@@ -5,3 +5,6 @@ parameters:
     - name: param1
       source:
         value: test-param
+    - name: param2
+      source:
+        secret: test-secret

config/samples/_v1_parameterset.yaml

@@ -3,4 +3,13 @@ kind: ParameterSet
 metadata:
   name: parameterset-sample
 spec:
-  # TODO(user): Add fields here
+  schemaVersion: 1.0.1
+  namespace: operator
+  name: porter-test-me
+  parameters:
+    - name: test-secret
+      source:
+        value: test-value
+    - name: test-secret
+      source:
+        secret: test-secret

config/samples/kustomization.yaml

@@ -5,4 +5,5 @@ resources:
 - _v1_agentconfig.yaml
 - _v1_agentaction.yaml
 - _v1_credentialset.yaml
+- _v1_parameterset.yaml
 # +kubebuilder:scaffold:manifestskustomizesamples

controllers/parameterset_controller.go

@@ -44,6 +44,7 @@ func (r *ParameterSetReconciler) SetupWithManager(mgr ctrl.Manager) error {
 		Complete(r)
 }
 
+// Reconcile is called when the spec of a parameter set is changed
 func (r *ParameterSetReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 
 	log := r.Log.WithValues("parameterSet", req.Name, "namespace", req.Namespace)
@@ -163,7 +164,6 @@ func (r *ParameterSetReconciler) runParameterSet(ctx context.Context, log logr.L
 	return r.runPorter(ctx, log, ps)
 }
 
-// This could be the main "runFunction for each controller"
 // Trigger an agent
 func (r *ParameterSetReconciler) runPorter(ctx context.Context, log logr.Logger, ps *porterv1.ParameterSet) error {
 	action, err := r.createAgentAction(ctx, log, ps)

controllers/parameterset_controller_test.go

@@ -63,7 +63,7 @@ func TestParameterSetReconiler_Reconcile(t *testing.T) {
 	require.NotNil(t, ps.Status.Action, "expected Action to be set")
 	var action porterv1.AgentAction
 	require.NoError(t, controller.Get(ctx, client.ObjectKey{Namespace: ps.Namespace, Name: ps.Status.Action.Name}, &action))
-	assert.Equal(t, "1", action.Labels[porterv1.LabelResourceGeneration], "The wrong action is set on the status")
+	assert.Equal(t, "1", action.Labels[porterv1.LabelResourceGeneration], "The wrong resource generation is set for the agent action")
 
 	// Mark the action as scheduled
 	action.Status.Phase = porterv1.PhasePending
@@ -97,7 +97,7 @@ func TestParameterSetReconiler_Reconcile(t *testing.T) {
 	// Verify the parameter set status was synced with the action
 	assert.NotNil(t, ps.Status.Action, "expected Action to still be set")
 	assert.Equal(t, porterv1.PhaseSucceeded, ps.Status.Phase, "incorrect Phase")
-	assert.True(t, apimeta.IsStatusConditionTrue(ps.Status.Conditions, string(string(porterv1.ConditionComplete))))
+	assert.True(t, apimeta.IsStatusConditionTrue(ps.Status.Conditions, string(porterv1.ConditionComplete)))
 
 	// Fail the action
 	action.Status.Phase = porterv1.PhaseFailed
@@ -153,7 +153,7 @@ func TestParameterSetReconiler_Reconcile(t *testing.T) {
 	// Verify that an action was created to delete it
 	require.NotNil(t, ps.Status.Action, "expected Action to be set")
 	require.NoError(t, controller.Get(ctx, client.ObjectKey{Namespace: ps.Namespace, Name: ps.Status.Action.Name}, &action))
-	assert.Equal(t, "3", action.Labels[porterv1.LabelResourceGeneration], "The wrong action is set on the status")
+	assert.Equal(t, "3", action.Labels[porterv1.LabelResourceGeneration], "The wrong resource generation is set for the agent action")
 
 	// Complete the delete action
 	action.Status.Phase = porterv1.PhaseSucceeded

docs/content/file-formats.md

@@ -11,6 +11,7 @@ The same goes for the name and labels fields.
 
 * [Installation](#installation)
 * [CredentialSet](#credentialset)
+* [ParameterSet](#parameterset)
 * [AgentAction](#agentaction)
 * [AgentConfig](#agentconfig)
 * [PorterConfig](#porterconfig)
@@ -35,6 +36,11 @@ In addition to the normal fields available on a [Porter Installation document](/
 
 See the glossary for more information about the [CredentialSet] resource.
 
+The CredentialSet spec is the same schema as the CredentialSet resource in Porter.
+You can copy/paste the output of the `porter credentials show NAME -o yaml` command into the CredentialSet resource spec (removing the status section).
+
+In addition to the normal fields available on a [Porter Credential Set document](/reference/file-formats/), the following fields are supported:
+
 ```yaml
 apiVersion: porter.sh/v1
 kind: CredentialSet
@@ -61,6 +67,45 @@ spec:
 
 [CredentialSet]: /operator/glossary/#credentialset
 
+## ParameterSet
+
+See the glossary for more information about the [ParameterSet] resource.
+
+The ParameterSet spec is the same schema as the ParameterSet resource in Porter.
+You can copy/paste the output of the `porter parameters show NAME -o yaml` command into the ParameterSet resource spec (removing the status section).
+
+In addition to the normal fields available on a [Porter Parameter Set document](/reference/file-formats/), the following fields are supported:
+
+
+```yaml
+apiVersion: porter.sh/v1
+kind: ParameterSet
+metadata:
+  name: parameterset-sample
+spec:
+  schemaVersion: 1.0.1
+  namespace: operator
+  name: porter-test-me
+  parameters:
+    - name: test-secret
+      source:
+        value: test-value
+    - name: test-secret
+      source:
+        secret: test-secret
+```
+
+| Field                     | Required | Default                            | Description                                                 |
+|---------------------------|----------|------------------------------------|-------------------------------------------------------------|
+| agentConfig               | false    | See [Agent Config](#agentconfig)   | Reference to an AgentConfig resource in the same namespace. |
+| porterConfig              | false    | See [Porter Config](#porterconfig) | Reference to a PorterConfig resource in the same namespace. |
+| parameters                | true     |                                    | List of parameter sources for the set |
+| parameters.name           | true     |                                    | The name of the parameter for the bundle |
+| parameters.source         | true     |                                    | The parameters type. Currently `vaule` and `secret` are the only supported sources |
+| **oneof** `parameters.source.secret` `parameters.source.value`   | true     |                                    | The plaintext value to use or the name of the secret that holds the parameter |
+
+[ParameterSet]: /operator/glossary/#parameterset
+
 ## AgentAction
 
 See the glossary for more information about the [AgentAction] resource.

docs/content/glossary.md

@@ -59,6 +59,28 @@ or [Hashicorp Vault](/plugins/hashicorp/) are configured instead.
 The operator creates a corresponding AgentAction to create, update or delete Porter credentials.
 Once created the credential set is available to an Installation resource via its spec file.
 
+### ParameterSet
+
+The [ParameterSet] custom resource represents a parameter set in Porter.
+
+[ParameterSet]: /operator/file-formats/#parameterset
+
+A ParameterSet supports a parameter source of `secret` for Porter secrets 
+plugins and `value` for plaintext values.
+
+Secrets source keys may vary depending on which [secret plugin](/plugins/) you have configured.
+The [host secrets plugin](/plugins/host/) is not a good fit for use with the Porter Operator because environment variables or
+files are not a recommended way to manage secrets on a cluster.
+The [kubernetes.secrets plugin](https://release-v1.porter.sh/plugins/kubernetes/#secrets) 
+can retrieve secrets from native Kubernetes secrets, and otherwise we 
+recommend that an external secret store such as [Azure KeyVault](/plugins/azure/#secrets)
+or [Hashicorp Vault](/plugins/hashicorp/) are configured instead.
+
+Value sources are stored in plaintext in the resource.
+
+The operator creates a corresponding AgentAction to create, update or delete Porter parameters.
+Once created the parameter set is available to an Installation resource via its spec file.
+
 ### AgentAction
 
 The [AgentAction] custom resource represents a Porter command that is run in the [PorterAgent](#porteragent).

installer/vanilla.porter.yaml

@@ -93,7 +93,7 @@ install:
       namespace: porter-operator-system
       name: mongodb
       chart: bitnami/mongodb
-      version: 10.27.2
+      version: 12.1.15
       set:
         auth.enabled: false
   - exec: