Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove docs (with note) about basic/custom form support. #6290

Merged
merged 2 commits into from
Jun 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions site/content/docs/latest/howto/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@ How-to guides can be thought of as directions that guide the reader through the
| How-to-guides | Get stuff done |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Access Control](./access-control.md) | Establish how users will authenticate with the Kubernetes clusters on which Kubeapps operates. |
| [Basic Form Support](./basic-form-support.md) | Configure your Helm chart in order to present a simple intuitive form during installation. |
| [Custom App View Support](./custom-app-view-support.md) | Inject custom app views for specific deployments. |
| [Custom Form Component Support](./custom-form-component-support.md) | Extend basic form with custom UI component or third party APIs for component values and validation. |
| [Managing application lifecycle with Kubeapps](./dashboard.md) | Manage and deploy applications in your cluster by using Kubeapps dashboard. |
| [Multi-cluster Support](./deploying-to-multiple-clusters.md) | Configure Kubeapps to target other clusters when deploying a package, in addition to the cluster on which Kubeapps is itself deployed. |
| [Offline Installation](./offline-installation.md) | Install Kubeapps in an offline environment (without Internet connection) |
Expand Down
255 changes: 1 addition & 254 deletions site/content/docs/latest/howto/basic-form-support.md
Original file line number Diff line number Diff line change
@@ -1,256 +1,3 @@
# Basic Form Support

**NOTE:** This feature is under heavy development. Some of the described below may change in the future.

Since Kubeapps 1.6.0, it's possible to include a JSON schema with a chart that defines the structure of the `values.yaml` file. This JSON schema is used with two goals:

- Validate that the given values satisfy the schema defined. In case the submitted values are not valid, the installation or upgrade will fail. This has been introduced with Helm v3.
- Present the user with a simpler so the chart is easier to deploy and configure.

The goal of this feature is to present the user with the most common parameters which are typically modified before deploying a chart (like username and password) in a more user-friendly form.

This document specifies what's needed to be defined in order to present this basic form to the users of a chart. If the basic form components do not fit your needs we also offer the ability for developers to inject their own custom components, the integration docs can be found [here](https://github.com/vmware-tanzu/kubeapps/blob/main/site/content/docs/latest/howto/custom-form-component-support.md).

## Create a values.schema.json

This file, introduced with Helm v3, is a [JSON Schema](https://json-schema.org/) that defines the structure of the `values.yaml` file of the chart, including as many validations as needed. If a chart includes its schema, the values used are validated before submitting the new release.

This file can define some or every possible value of the chart. Once it's written it should be included in the Helm package. The proposal to include it in Helm can be found [here](https://github.com/helm/helm/issues/5812).

## Additional annotations used to identify basic parameters

In order to identify which values should be presented in the form, it's necessary to include some special tags.

First of all, it's necessary to specify the tag `form` and set it to `true`. All the properties marked with this tag in the schema will be represented in the form. For example:

```json
"wordpressUsername": {
"type": "string",
"form": true
},
```

With the definition above, we are marking the value `wordpressUsername` as a value to be represented in the form. Note that the `type` tag, apart than for validating that the submitted value has the correct type, will be used to render the proper HTML components to represent the input in the form:

![username-input](../img/username-input.png)

In addition to the `type`, there are other tags that can be used to customize the way the parameter is represented:

- `title` is used to render the title of the parameter. If it's not specified, Kubeapps will use the path of the value (i.e. `credentials.username`).
- `description` is used to include additional information of the parameter.
- `default` is used to set a default value. Note that this field will only be used if the `values.yaml` file doesn't have already a default value for the parameter.

### Custom type: Slider

It's possible to render a component as a slider, users can then drag and drop this slider to select their preferred value:

![disk-input](../img/disk-input.png)

In order to render a slider, there are some requirements and additional tags that you may need to set:

- The supported types are `string`, `integer` and `numeric`.
- It's necessary to specify the tag `render` and set it to `slider`.
- The tag `sliderMin` identifies the minimum value the slider allows (this can be bypassed writing a smaller value in the input).
- The tag `sliderMax` identifies the maximum value the slider allows (this can be bypassed writing a greater value in the input).
- The tag `sliderStep` identifies the step the slider will increment or decrement the value when moved.
- The tag `sliderUnit` specifies the unit of the value to set. For example `Gi`.

This is an example of a slider param:

```json
"size": {
"type": "string",
"title": "Disk Size",
"form": true,
"render": "slider",
"sliderMin": 1,
"sliderMax": 100,
"sliderUnit": "Gi"
}
```

### Custom type: TextArea

It's possible to render a component as a textArea instead of a single-line string.

In order to render a component as a textArea, it's necessary to specify the tag `render` and set it to `textArea`.

This is an example of a textArea param:

```json
"size": {
"type": "string",
"title": "Configuration",
"description": "Configuration to be used",
"form": true,
"render": "textArea"
}
```

### Drop-down lists

When a property defines an `enum` tag as constraint, it will be rendered as a drop-down list.

This is an example:

```json
"databaseType": {
"type": "string",
"form": true,
"enum": ["mariadb", "postgresql"],
"title": "Database Type",
"description": "Allowed values: \"mariadb\" and \"postgresql\""
}
```

![drop-down](../img/drop-down.png)

A drop-down list cannot be empty or have its value unselected. For this purpose, it is necessary to add an explicit empty value on the enum constraints.

### Subsections

When a property of type `object` is set with a `form` identifier, it will be rendered as a subsection. A subsection is a set of parameters that are grouped together:

![hostname-section](../img/hostname-section.png)

All the parameters within an `object` will be rendered in the subsection.

Note that in some cases, a parameter cause that the rest of the parameters are no longer relevant. For example, setting `ingress.enabled` to `false` makes the `ingress.hostname` irrelevant. To avoid confusion, you can hide that parameter setting the special tag `hidden`. The tag `hidden` can be a `string` pointing to the parameter that needs to be `true` to hide the element, or an `object` to also set the value that the pointed value needs to match as shown below:

```json
{
"hidden": {
"value": "foo",
"path": "bar"
}
}
```

When using an `object` to set the `hidden` tag, you can also specify an array of conditions to match, and the conditional operator to use (currently supported: `and`, `or`, `nor`). The format is shown below:

```json
{
"hidden": {
"conditions": [
{
"value": "foo",
"path": "bar"
},
{
"value": "baz",
"path": "qux"
}
],
"operator": "or"
}
```

This is an example for a subsection with a parameter that can be hidden:

```json
"ingress": {
"type": "object",
"form": "ingress",
"title": "Ingress Details",
"properties": {
"enabled": {
"type": "boolean",
"form": "enableIngress",
"title": "Use a custom hostname",
"description": "Enable the ingress resource that allows you to access the WordPress installation."
},
"hostname": {
"type": "string",
"form": "hostname",
"title": "Hostname",
"hidden": {
"conditions": [{
"path": ingress/enabled,
"value": "false"
}],
"operator": "and"
}
}
}
},
```

Note that the parameter that hides another parameter doesn't need to be within the section itself. In this other example, `mariadb.enabled` is used to hide some parameters within `externalDatabase`:

```json
"mariadb": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"title": "Use a new MariaDB database hosted in the cluster",
"form": "useSelfHostedDatabase",
}
}
},
"externalDatabase": {
"type": "object",
"title": "External Database Details",
"form": "externalDatabase",
"properties": {
"host": {
"type": "string",
"form": "externalDatabaseHost",
"title": "Database Host",
"hidden": "mariadb/enabled"
},
}
},
```

A parameter can also be hidden based on the deployment event `install` or `upgrade`, wherever they are no longer relevant.

```json
"mariadb": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"title": "Use a new MariaDB database hosted in the cluster",
"form": "useSelfHostedDatabase",
"hidden": {
"event": "upgrade"
}
}
}
},
```

The `event` condition can be combined into a array of conditions in the same way:

```json
"mariadb": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"title": "Use a new MariaDB database hosted in the cluster",
"form": "useSelfHostedDatabase",
"hidden": {
"conditions": [
{
"event": "upgrade"
},
{
"path": "mariadb/enabled",
"value": "true"
}],
"operator": "or"
}
}
}
},
```

## Example

This is a [working example for the WordPress chart](https://github.com/bitnami/charts/blob/main/bitnami/wordpress/values.schema.json)

And the resulting form:

![basic-form](../img/basic-form.png)
**NOTE:** Support for the basic form support feature had to be removed in v2.6.0 when the Bitnami catalog updated to include standard json schema files for each chart. We hope to re-enable the ability to define basic forms for users (see [#5988](https://github.com/vmware-tanzu/kubeapps/issues/5988)) rather than the current display of all fields from the values.yaml.
4 changes: 2 additions & 2 deletions site/content/docs/latest/howto/custom-app-view-support.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Custom App View Support

In addition to our [custom form component support](https://github.com/vmware-tanzu/kubeapps/blob/main/site/content/docs/latest/howto/custom-form-component-support.md) we now support the ability for developers to inject custom app views for specific deployments.
Kubeapps supports the ability for developers to inject custom app views for specific deployments.

## Step-by-step integration process

Expand All @@ -17,7 +17,7 @@ In addition to our [custom form component support](https://github.com/vmware-tan

This will tell the frontend to load the custom bundle for the apache helm chart in the bitnami repo.

1. And just like the custom form components the bundle can be added via the command line:
1. The bundle can be added via the command line:

```bash
helm install bitnami/kubeapps --set-file dashboard.customComponents=*path to file* <other_flags>
Expand Down
57 changes: 1 addition & 56 deletions site/content/docs/latest/howto/custom-form-component-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,59 +2,4 @@

This is an extension to the [basic form support](./basic-form-support.md#basic-form-support)

## Possible use cases

- Custom UI component that are not yet supported by the basic components (e.g: radio selectors)
- Consuming third party APIs for component values and validation

## Step-by-step integration process

1. First you will need a react component to render instead of the default Kubeapps form components. You're React components must be compiled into a JS file so that they can be interpreted by the browser since they cannot natively parse `.jsx` or `.tsx` files. You can compile `jsx` or `tsx` into js with tools like webpack, create-react-app, babel, etc. If you just want to try this feature out and you don't have a component yet we provide some test files you can try (Do not try to load the `jsx` file since browsers cannot parse it! We simply include it so that you can see the pre-compiled version of the `.js` files).
2. The easiest way to add inject the file in is via the command line. You can do it via the following command:

```bash
helm install bitnami/kubeapps --set-file dashboard.customComponents=*path to file* <other_flags>
```

Note: The file can be located anywhere on your file system or even a remote source!
Alternatively we provide remote loading by setting the `remoteComponentsUrl` value to the URL that is serving your bundle. If this is not set, the configmap will be the default loader.

3. Once the deployment is complete you will need a values json that will signal to Kubeapps that we want to render a custom component and not one fo the provided ones. To do that you will need a `values.json.schema` that has a `customComponent` key, more info [here](./custom-form-component-support.md#render-a-custom-component).

## Render a custom component

Signaling to the Kubeapps dashboard that you want to render a custom component is pretty straight forward. Simply add a `customComponent` field to any form parameter defined in the `values.json.schema` and that will tell the react application to fetch the component from the custom js bundle. An example parameter could look like:

```json
"databaseType": {
"type": "string",
"form": true,
"enum": ["mariadb", "postgresql"],
"title": "Database Type",
"description": "Allowed values: \"mariadb\" and \"postgresql\"",
"customComponent": {
"type": "radio",
"className": "primary-radio"
}
}
```

Note: The `customComponent` field **MUST BE AN OBJECT**. This design decision was made so that developers can pass extra values/properties into their custom components should they require them.

## Updating Helm values with custom components

Custom form components would be useless without the ability to interact with the YAML state. To do this your custom components should be set up to receive 2 props: `handleBasicFormParamChange` and `param`. `param` is the current json object this is being rendered (denoted by the `customComponent` field) and `handleBasicFormParamChange` which is a function that updates the YAML file. An example of how you use this function can be found in any of the BasicDeploymentForm components such as the [SliderParam](https://github.com/vmware-tanzu/kubeapps/blob/main/dashboard/src/components/DeploymentFormBody/BasicDeploymentForm/SliderParam.tsx#L47-L53).

```javascript
const handleParamChange = (newValue: number) => {
handleBasicFormParamChange(param)({
currentTarget: {
value: newValue,
},
} as React.FormEvent<HTMLInputElement>);
};
```

## Tips

To help you get started we provide some examples that you can try [here](https://github.com/vmware-tanzu/kubeapps/tree/main/site/content/docs/latest/reference/examples). The three files should give you a good idea about how to start developing and building your own custom components. `CustomComponent.jsx` is a super simple react component that takes the `handleBasicFormParamChange` and `param` props and renders a button that changes the value to 'test'. `CustomComponent.js` is the JavaScript variant of `CustomComponent.jsx` and `CustomComponent.min.js` is a minified js bundle created using [remote-component-starter](https://github.com/Paciolan/remote-component-starter), which is specifically made to help build components that you want to load remotely with the [remote-component](https://github.com/Paciolan/remote-component) tool used by Kubeapps.
**NOTE:** Support for the basic form support feature had to be removed in v2.6.0 when the Bitnami catalog updated to include standard json schema files for each chart and as a result, also for the custom form component support. We hope to re-enable the ability to define basic forms for users (see [#5988](https://github.com/vmware-tanzu/kubeapps/issues/5988)) rather than the current display of all fields from the values.yaml.
Binary file removed site/content/docs/latest/img/basic-form.png
Binary file not shown.
Binary file removed site/content/docs/latest/img/disk-input.png
Binary file not shown.
Binary file removed site/content/docs/latest/img/drop-down.png
Binary file not shown.
Binary file removed site/content/docs/latest/img/hostname-section.png
Binary file not shown.
Binary file removed site/content/docs/latest/img/username-input.png
Binary file not shown.
4 changes: 0 additions & 4 deletions site/data/docs/latest-toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,12 +56,8 @@ toc:
page: Using the dashboard
- url: /howto/access-control
page: Access Control
- url: /howto/basic-form-support
page: Basic Form Support
- url: /howto/custom-app-view-support
page: Custom App View Support
- url: /howto/custom-form-component-support
page: Custom Form Component Support
- url: /howto/deploying-to-multiple-clusters
page: Multi-cluster Support
- url: /howto/offline-installation
Expand Down
Loading