Merge pull request #56 from stefanprodan/values-docs

Add values files docs and examples

cmd/timoni/apply.go

@@ -81,7 +81,12 @@ The apply command performs the following steps:
   --force
 
   # Install or upgrade an instance with custom values from stdin
-  cat values.cue | timony apply -n apps app oci://docker.io/org/module -v 1.0.0 --values -
+  echo "values: replicas: 2" | timoni apply -n apps app oci://docker.io/org/module --values -
+
+  # Install or upgrade an instance with values in YAML and JSON format
+  timoni apply -n apps app oci://docker.io/org/module \
+  --values ./values-1.yaml \
+  --values ./values-2.json
 `,
 	RunE: runApplyCmd,
 }
@@ -105,7 +110,7 @@ func init() {
 	applyCmd.Flags().VarP(&applyArgs.version, applyArgs.version.Type(), applyArgs.version.Shorthand(), applyArgs.version.Description())
 	applyCmd.Flags().VarP(&applyArgs.pkg, applyArgs.pkg.Type(), applyArgs.pkg.Shorthand(), applyArgs.pkg.Description())
 	applyCmd.Flags().StringSliceVarP(&applyArgs.valuesFiles, "values", "f", nil,
-		"The local path to values.cue files.")
+		"The local path to values files (cue, yaml or json format).")
 	applyCmd.Flags().BoolVar(&applyArgs.force, "force", false,
 		"Recreate immutable Kubernetes resources.")
 	applyCmd.Flags().BoolVar(&applyArgs.dryrun, "dry-run", false,

cmd/timoni/build.go

@@ -71,7 +71,7 @@ func init() {
 	buildCmd.Flags().VarP(&buildArgs.version, buildArgs.version.Type(), buildArgs.version.Shorthand(), buildArgs.version.Description())
 	buildCmd.Flags().VarP(&buildArgs.pkg, buildArgs.pkg.Type(), buildArgs.pkg.Shorthand(), buildArgs.pkg.Description())
 	buildCmd.Flags().StringSliceVarP(&buildArgs.valuesFiles, "values", "f", nil,
-		"The local path to values.cue files.")
+		"The local path to values files (cue, yaml or json format).")
 	buildCmd.Flags().StringVarP(&buildArgs.output, "output", "o", "yaml",
 		"The format in which the Kubernetes objects should be printed, can be 'yaml' or 'json'.")
 	buildCmd.Flags().Var(&buildArgs.creds, buildArgs.creds.Type(), buildArgs.creds.Description())

cmd/timoni/bundle_apply.go

@@ -58,8 +58,8 @@ var bundleApplyCmd = &cobra.Command{
   -f ./bundle.cue \
   -f ./bundle_secrets.cue
 
-  # Install instances from a bundle using stdin
-  cat ./bundle.cue | timony bundle apply -f -
+  # Pass secret values from stdin
+  cat ./bundle_secrets.cue | timoni bundle apply -f ./bundle.cue -f -
 `,
 	RunE: runBundleApplyCmd,
 }

docs/quickstart.md

@@ -72,7 +72,7 @@ timoni -n test status podinfo
 
 ## Configure a module instance
 
-To customise an instance, you can supply the configuration values using `values.cue` files.
+To customise an instance, you can supply the configuration values using [values files](values.md).
 
 For example, to set the [QoS](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/)
 class to guaranteed, create a `qos-values.cue` file that sets the resources limits equal to the requests:
@@ -100,27 +100,6 @@ be made on the cluster with `timoni apply --dry-run --diff`.
 
 To learn more about all the available apply options, use `timoni apply --help`.
 
-In the values files you can use arithmetic operations,
-string interpolation and everything else that CUE std lib supports.
-For example, to set the resources limits to 2x requests:
-
-```cue
-values: {
-	_mcpu: 500
-	_mem:  256
-	resources: {
-		requests: {
-			cpu:    "\(_mcpu)m"
-			memory: "\(_mem)Mi"
-		}
-		limits: {
-			cpu:    "\(_mcpu*2)m"
-			memory: "\(_mem*2)Mi"
-		}
-	}
-}
-```
-
 ## Uninstall a module instance
 
 To uninstall an instance and delete all the managed Kubernetes resources:

docs/values.md

@@ -0,0 +1,85 @@
+# Values
+
+Values are used to customise a module instance by providing Timoni with a config object.
+The config schema, constraints and the default values are contained in the module definition.
+
+## Values files
+
+Values can be supplied as CUE, YAML or JSON files
+to the `timoni apply <instance-name> [--values <path/to/values>]` command.
+
+Given the config definition:
+
+```go
+#Config: {
+	image: {
+		repository: *"docker.io/stefanprodan/podinfo" | string
+		tag:        *"6.3.0" | string
+		pullPolicy: *"IfNotPresent" | string
+	}
+	replicas:   *1 | int & >0
+	resources?: corev1.#ResourceRequirements
+}
+```
+
+A values file can override default values such as an image repository:
+
+```go
+values: {
+	image: repository: "ghcr.io/stefanprodan/podinfo"
+}
+```
+
+And set optional values such as resources limits:
+
+```go
+values: {
+	resources: limits: {
+		cpu:    "100m"
+		memory: "128Mi"
+	}
+}
+```
+
+To create an instance using the custom values, both files can be supplied with:
+
+```shell
+timoni -n default apply podinfo \
+  oci://ghcr.io/stefanprodan/modules/podinfo \
+  --values image-values.cue \
+  --values limits-values.cue
+```
+
+Values can also be supplied by piping a CUE object, for example:
+
+```shell
+echo "values: replicas: 2" | timoni -n default apply podinfo \
+  oci://ghcr.io/stefanprodan/modules/podinfo \
+  --values image-values.cue \
+  --values limits-values.cue
+```
+
+At apply time, Timoni merges the values, validates them
+against the config schema and creates the instance.
+
+When values are supplied as CUE files, they can contain arithmetic operations,
+string interpolation and everything else that CUE std lib supports.
+
+For example, to set the resources limits to 2x requests:
+
+```go
+values: {
+	_mcpu: 500
+	_mem:  256
+	resources: {
+		requests: {
+			cpu:    "\(_mcpu)m"
+			memory: "\(_mem)Mi"
+		}
+		limits: {
+			cpu:    "\(_mcpu*2)m"
+			memory: "\(_mem*2)Mi"
+		}
+	}
+}
+```

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
   - Quickstart: quickstart.md
   - Topics:
       - Module Structure: module.md
+      - Values files: values.md
   - Automation:
       - GitHub Actions: github-actions.md
       - GitOps with Flux: gitops-flux.md