diff --git a/blog/2026-07-27-epinio-1-14-1.md b/blog/2026-07-27-epinio-1-14-1.md new file mode 100644 index 00000000000..b63b90b5a6f --- /dev/null +++ b/blog/2026-07-27-epinio-1-14-1.md @@ -0,0 +1,67 @@ +--- +slug: epinio-1-14-1 +title: Announcing Epinio 1.14.1! +authors: [epinio] +tags: [release] +date: 2026-07-27 +--- + +Epinio 1.14.1 is here, and there is a lot to talk about! This release includes the +usual bug fixes, dependency updates, and maintenance, along with several new features. + +We encourage you to review the documentation for [upgrading Epinio](https://docs.epinio.io/reference/upgrading). In this release specifically we have made changes to CRDs and added new user permissions, so it is important to review the upgrade documentation before upgrading. + + + +## New Features and Improvements + +- AppCharts can be managed via the UI or CLI. +- Catalog Services can be managed via the UI or CLI. +- Builder images can be managed via the UI or CLI, search existing builder images, and manually enter remote ones. +- [Git configs](https://docs.epinio.io/reference/concepts/git_configuration) have been overhauled for wider provider support and ease of use: + - Use git configs for GitHub, GitHub Enterprise, and GitLab. + - Manage git configs via the UI or CLI. + - Use a global configuration for org-wide git configs. + - Explicitly select a git config from the application creation flow. +- Bulk delete for applications, service instances, and configurations is now available via the UI. +- [Gateway API](https://docs.epinio.io/how-to/operator/networking/enable_gateway_api) support. + +## App Watch (Experimental) + +Due to feedback from multiple users, we have added [Epinio App Watch](https://docs.epinio.io/how-to/developer/concepts/app_watch) as a experimental feature. App Watch watches your application for changes and automatically redeploys it when changes are detected, so you can develop the way you deploy and rapidly iterate on applications in-cluster. Below is a short demo of it in action. + + + +## MCP + +The [Epinio MCP server](https://github.com/epinio/mcp) has been promoted from experimental to beta! A lot of work has gone into reducing external dependencies and using Epinio natively to accomplish much of the MCP server's functionality. We have also made various bug fixes and improvements, and +a v1.0.0 version is coming soon. + +## Documentation + +This release includes a significant overhaul of the [documentation site](https://docs.epinio.io). + +- Reorganized and cleaned up the documentation for easier navigation. +- Removed documentation for releases prior to 1.11.0. +- Refreshed the community tab and removed the Related Projects tab. +- Added documentation for Minio to SeaweedFS migration. +- Added documentation for the Epinio MCP server. +- Updated to the majority of pages to reflect the current state of Epinio and its features. + +## Fixes + +- The Application Detail page now refreshes regularly to show the latest application state. +- Improved error handling for application creation and deployment. +- Fixed Export Application failing silently. +- Several fixes and improvements around table and dropdown loading. + +## Dependency updates +Updated server, UI, and Helm chart dependencies. + +--- + +For the complete technical changelog, see the +[1.14.1 release on GitHub](https://github.com/epinio/epinio/releases/tag/v1.14.1). diff --git a/docs/getting-started/install-mcp.md b/docs/getting-started/install-mcp.md index a7c12780ef8..64a7b7b7275 100644 --- a/docs/getting-started/install-mcp.md +++ b/docs/getting-started/install-mcp.md @@ -12,21 +12,22 @@ doc-topic: [epinio, getting-started, mcp] The [Epinio MCP server](https://github.com/epinio/mcp) exposes Epinio as tools for AI agents over the [Model Context Protocol](https://modelcontextprotocol.io). It runs on your cluster and talks to the Epinio API on the agent's behalf. For the -full tool list and the optional capabilities, see the +full tool list and the optional elevated tier, see the [MCP server reference](../reference/mcp). -:::caution Experimental -The MCP server is under active development and not yet stable. Tool names, -capabilities, and install steps may change. It is not recommended for production -use. +:::caution Beta +The MCP server is in beta. Tool names and options may still change, and it is +not yet recommended for production use. ::: ## Prerequisites -- A Kubernetes cluster with [Epinio](./install-epinio.md) installed. +- A Kubernetes cluster with [Epinio](./install-epinio.md) **1.14.1 or later** + installed. The server relies on the builder-image, catalog-service, and + app-chart CRUD API and the source-retrieval endpoint added in 1.14.1, so it + will not work against earlier releases. - `kubectl` and the [`epinio` CLI](./install-cli.md) pointed at your cluster. -- An Epinio namespace to deploy into (default: `epinio`). -- [`task`](https://taskfile.dev) (optional, used by the `epinio push` path below). +- `make` and a Go toolchain, plus a clone of [epinio/mcp](https://github.com/epinio/mcp). ## Choose an install path @@ -34,29 +35,21 @@ There are two ways to install the server. Most users want the first. | Path | Use when | | --- | --- | -| **`epinio push` (managed)** | You want Epinio to own the lifecycle (push, logs, restart, scale), just like any other app. | +| **`make setup` (managed)** | You want Epinio to own the lifecycle (push, logs, restart, scale), just like any other app. | | **`kubectl apply` (adopted)** | You want the server managed outside Epinio's REST path, and prefer to finish setup through conversation with the agent. | -## Install with `epinio push` (recommended) +## Install with `make setup` (recommended) -The repository ships a `Taskfile.yml` that automates the full setup. After -cloning [epinio/mcp](https://github.com/epinio/mcp) and editing `epinio.yml` with -your cluster credentials: +Clone [epinio/mcp](https://github.com/epinio/mcp), set your cluster details in +`epinio.yml`, and run: ```bash -task setup +make setup ``` -`task setup` runs these steps in order, and each can be run on its own for partial -runs or re-runs: - -```bash -task cluster-prep # (cluster-admin, once per cluster) manifests + namespace label -task s3-service # create and wait for the epinio-s3-gateway service -task configure-s3 # create the epinio-s3-gateway Epinio configuration (idempotent) -task push # epinio push from the repo root -task verify # smoke-test /healthz and /readyz -``` +This targets the `mcp` namespace (creating it if needed), pushes the server, and +smoke-tests `/healthz` and `/readyz`. Override the namespace with +`make setup NAMESPACE=`, and run `make help` to see every target. `epinio.yml` carries the connection details. Fill in the `environment` section with your cluster's API URL and credentials (default `admin` / `password`): @@ -72,18 +65,31 @@ For OIDC clusters, leave the username and password empty and set `EPINIO_TOKEN`, `EPINIO_REFRESH_TOKEN`, and `EPINIO_TOKEN_ENDPOINT` instead. The push runs the full build cycle (upload source, stage, deploy, wait for ready) -and assigns a route, for example `https://epinio-mcp.192.168.X.X.sslip.io/mcp`. +and assigns a route, for example `https://epinio-mcp.192.168.X.X.sslip.io`. The +MCP endpoint is that route's root — point your agent at the URL as-is (no `/mcp` +suffix). -For the manual, step-by-step walkthrough (useful when a step fails), see -[`INSTALL.md`](https://github.com/epinio/mcp/blob/main/INSTALL.md) in the -repository. +### Elevated tier (optional) + +The core install wires only to the Epinio API. To turn on the opt-in +[elevated tier](../reference/mcp#elevated-tier) — workload adoption, which reaches +directly into Kubernetes — edit `epinio-elevated.yml` and run: + +```bash +make elevated-setup +``` + +This registers the `standard-elevated` app chart (a one-time, cluster-admin step) +and pushes the server with `EPINIO_MCP_ELEVATED` set. Switching a running server +between the core and elevated installs recreates it (the app chart can't change in +place). ## Install with `kubectl apply` -This path stands the server up as a plain Kubernetes workload. The install -manifest is self-contained: it creates the namespace, the server's ServiceAccount -and RBAC, the Deployment and Service, and an Epinio `App` record so -`epinio app list/show/logs/exec` keep working. +This path stands the server up as a plain Kubernetes workload with the adoption +RBAC. The install manifest is self-contained: it creates the namespace, the +server's ServiceAccount and RBAC, the Deployment and Service, and an Epinio `App` +record so `epinio app list/show/logs` keep working. Deploy the server (edit the image tag, credentials, and Ingress host first): @@ -101,28 +107,6 @@ Run enable_capability for self_adoption. To upgrade, edit the image tag and re-apply `install/epinio-mcp.yaml`; to uninstall, run `kubectl delete -f install/epinio-mcp.yaml`. -### Enable source-reading tools (app_editing) - -The `app_editing` capability (`get_app_source`, `list_app_files`) needs an S3 -gateway. The prerequisites ship in the repo's -[`manifests/`](https://github.com/epinio/mcp/tree/main/manifests). As a cluster -admin, register the S3 gateway catalog entry and let Epinio manage the `epinio` -namespace: - -```bash -kubectl apply -f manifests/s3-gateway-catalog-entry.yaml -kubectl label namespace epinio app.kubernetes.io/component=epinio-namespace --overwrite -``` - -Then have the agent provision and wire up the gateway: - -```text -Run enable_capability for app_editing. -``` - -`enable_capability` creates the `s3-gateway` service instance, reads its -credentials, binds them to the server, and restarts the pod. - ## Verify the server is up The server exposes two plain-HTTP probes: @@ -138,7 +122,7 @@ curl https://epinio-mcp./readyz A healthy `/readyz` response reports the Epinio version it reached: ```json -{"epinio":{"kube_version":"...","platform":"...","version":"..."},"status":"ok","version":"0.6.0"} +{"epinio":{"kube_version":"...","platform":"...","version":"..."},"status":"ok","version":"..."} ``` ## See also diff --git a/docs/how-to/developer/concepts/app-charts/app-charts.mdx b/docs/how-to/developer/concepts/app-charts/app-charts.mdx index 8ef1d2a5ddf..c3a1897142c 100644 --- a/docs/how-to/developer/concepts/app-charts/app-charts.mdx +++ b/docs/how-to/developer/concepts/app-charts/app-charts.mdx @@ -15,6 +15,7 @@ import TabItem from '@theme/TabItem'; This guide explores working with application charts. App charts are reusable application templates packaged as Helm charts that allow users to deploy preconfigured applications. For more information see the [application charts reference](../../../../reference/concepts/appcharts.md) page. ## View Application Charts + @@ -37,7 +38,95 @@ epinio app chart list -### Application Charts CRUD Coming Soon! +## Create an Application Chart + + + + +Click **Create** on the Application Charts page to open the creation modal. Here you can provide a name and short description which will be displayed when creating an application, a detailed description for display in the table, as well as a Helm Chart URL and/or a Helm Repo URL. You can also establish settings that will prompt the user for values during app creation if they select the corresponding chart. + +Create App Chart Modal + + + + + +Create an application chart: + +```console +epinio app chart create --name mychart \ + --short-description "My application chart" \ + --description "A longer description of my application chart" \ + --helm-repo https://charts.example.com \ + --helm-chart https://charts.example.com/mychart-1.0.0.tgz \ + --set replicaCount=2 \ + --set image.tag=latest +``` + +The `--set` flag takes a `key=value` pair and can be repeated to provide multiple values. + + + + +## Edit an Application Chart + + + + +Select **Edit** from the action menu for the row of the app chart you wish to edit. Use caution when editing charts that are being used by applications, as you may cause issues for future rebuilds. + +Edit App Chart Modal + + + + + +Update an application chart. Flags you do not set leave the corresponding fields unchanged: + +```console +epinio app chart update mychart \ + --short-description "An updated description" \ + --helm-chart https://charts.example.com/mychart-1.1.0.tgz \ + --set replicaCount=3 +``` + + + + +## Delete an Application Chart + + + + +Open the action menu for the application chart and select **Delete**. Confirm the deletion. + +Delete App Chart Modal + + + + + +Delete an application chart: + +```console +epinio app chart delete mychart +``` + + + + ## Additional CLI Commands For additional documentation on the CLI commands above, along with additional commands, see the [epinio app chart](../../../../reference/cli/app/chart/epinio_app_chart.md) CLI reference. \ No newline at end of file diff --git a/docs/how-to/developer/concepts/app-charts/charts-create-modal.png b/docs/how-to/developer/concepts/app-charts/charts-create-modal.png new file mode 100644 index 00000000000..11dd411cabf Binary files /dev/null and b/docs/how-to/developer/concepts/app-charts/charts-create-modal.png differ diff --git a/docs/how-to/developer/concepts/app-charts/charts-delete-modal.png b/docs/how-to/developer/concepts/app-charts/charts-delete-modal.png new file mode 100644 index 00000000000..666071635ea Binary files /dev/null and b/docs/how-to/developer/concepts/app-charts/charts-delete-modal.png differ diff --git a/docs/how-to/developer/concepts/app-charts/charts-edit-modal.png b/docs/how-to/developer/concepts/app-charts/charts-edit-modal.png new file mode 100644 index 00000000000..eb27c9adb38 Binary files /dev/null and b/docs/how-to/developer/concepts/app-charts/charts-edit-modal.png differ diff --git a/docs/how-to/developer/concepts/app-charts/charts-screen.png b/docs/how-to/developer/concepts/app-charts/charts-screen.png index c5d9c1f38ca..321a988ac0a 100644 Binary files a/docs/how-to/developer/concepts/app-charts/charts-screen.png and b/docs/how-to/developer/concepts/app-charts/charts-screen.png differ diff --git a/docs/how-to/developer/concepts/.app_watch.md b/docs/how-to/developer/concepts/app_watch.md similarity index 82% rename from docs/how-to/developer/concepts/.app_watch.md rename to docs/how-to/developer/concepts/app_watch.md index a82e0bcbed0..4437db2e0e9 100644 --- a/docs/how-to/developer/concepts/.app_watch.md +++ b/docs/how-to/developer/concepts/app_watch.md @@ -9,6 +9,11 @@ doc-topic: [epinio, how-to, use-develop, app-watch] doc-persona: [epinio-developer] --- +:::caution Experimental +app watch is experimental: it has been validate on a limited set of frameworks +and builder iamges. Behavior on other app types and binary layouts is not yet +guaranteed. +::: `epinio app watch` shortens the edit-compile-test loop by syncing local changes directly into a running pod, skipping the full buildpack pipeline on every save. @@ -16,13 +21,16 @@ directly into a running pod, skipping the full buildpack pipeline on every save. `app watch` has two phases: -**Startup (first run)** +**Startup (every run)** -On the first `app watch` run (no local `.epinio-patch-state` file), Epinio -patches the app's existing source blob, runs buildpack staging, and patches the -running deployment to inject a supervisor wrapper as PID 1. The supervisor -starts your app and relaunches it when sync delivers an updated binary or -source files. +Each time you start `app watch`, Epinio patches the app's existing source +blob, runs buildpack staging, and patches the running deployment to inject a +supervisor wrapper as PID 1. The supervisor starts your app and relaunches it +when sync delivers an updated binary or source files. + +The startup push runs on every invocation, not just the first. This is +deliberate: a normal `epinio app push` (or any redeploy) recreates the pod +without the supervisor, so re-running `app watch` always re-establishes it. **Sync (subsequent runs)** @@ -56,9 +64,9 @@ epinio app push my-app epinio app watch my-app ``` -Run `epinio app push` once before the first `app watch` session. On the first -watch run, Epinio restages the app and installs the supervisor; after that, -save any source file and the terminal will show sync progress: +Run `epinio app push` once so the app exists. When you start `app watch`, +Epinio restages the app and installs the supervisor; after that, save any +source file and the terminal will show sync progress: ```text Synced in 312ms (via API) @@ -81,8 +89,8 @@ On every save, `app watch` runs `build_cmd`, uploads the new binary into the pod, and the supervisor restarts the app automatically. No extra tooling required. -Delete `.epinio-patch-state` and re-run `app watch` after `go.mod` changes -to trigger a fresh buildpack run that re-resolves dependencies. +After `go.mod` changes, restart `app watch`: the startup push re-runs the +buildpack and re-resolves dependencies before watching resumes. ### Node.js @@ -176,18 +184,13 @@ ignore list makes both change detection and uploads faster. ## State file -`app watch` writes `.epinio-patch-state` in the source directory after a -successful startup push. This file records the file hashes used to detect -changes on the next run. - -If this file is present, `app watch` skips the startup push and goes straight -into sync mode. To force a fresh startup push (for example, after a dependency -change), delete the state file: +`app watch` writes `.epinio-patch-state` in the source directory during a +watch session. This file records the file hashes used to detect changes +between poll cycles. -```console -rm .epinio-patch-state -epinio app watch my-app -``` +The state file is cleared automatically at the start of every `app watch` +run, so each session begins with a fresh startup push that reinstalls the +supervisor. You do not need to delete it by hand. While an app is under `watch`, its deployment keeps the supervisor wrapper and pinned image. Run a regular `epinio app push` or `epinio app restage` when you diff --git a/docs/how-to/developer/concepts/applications/applications.mdx b/docs/how-to/developer/concepts/applications/applications.mdx index cbb3df8c452..82a74a6b2ad 100644 --- a/docs/how-to/developer/concepts/applications/applications.mdx +++ b/docs/how-to/developer/concepts/applications/applications.mdx @@ -56,7 +56,9 @@ Provide your application source to Epinio. If you have an [application manifest] - GitHub - GitLab -After providing your source, select the [application chart](../app-charts/app-charts.mdx) and builder image you would like Epinio to use. +Selecting any of the Git options will allow you to select from your [git configurations](../git-configs/git-configs.mdx) so Epinio can access prive repos/projects. + +After providing your source, select the [builder image](../builder-images/builder-images.mdx) you would like Epinio to use when building your application and the [application chart](../app-charts/app-charts.mdx) you would like Epinio to use when deploying it. diff --git a/docs/how-to/developer/concepts/builder-images/builder-create-modal.png b/docs/how-to/developer/concepts/builder-images/builder-create-modal.png new file mode 100644 index 00000000000..922d266e33b Binary files /dev/null and b/docs/how-to/developer/concepts/builder-images/builder-create-modal.png differ diff --git a/docs/how-to/developer/concepts/builder-images/builder-delete-modal.png b/docs/how-to/developer/concepts/builder-images/builder-delete-modal.png new file mode 100644 index 00000000000..031648bdd3b Binary files /dev/null and b/docs/how-to/developer/concepts/builder-images/builder-delete-modal.png differ diff --git a/docs/how-to/developer/concepts/builder-images/builder-edit-modal.png b/docs/how-to/developer/concepts/builder-images/builder-edit-modal.png new file mode 100644 index 00000000000..5dfc325c670 Binary files /dev/null and b/docs/how-to/developer/concepts/builder-images/builder-edit-modal.png differ diff --git a/docs/how-to/developer/concepts/builder-images/builder-images.mdx b/docs/how-to/developer/concepts/builder-images/builder-images.mdx new file mode 100644 index 00000000000..e7e31ae328f --- /dev/null +++ b/docs/how-to/developer/concepts/builder-images/builder-images.mdx @@ -0,0 +1,132 @@ +--- +sidebar_label: Builder Images +sidebar_position: 7 +title: Builder Images +description: How to use Epinio builder images. +keywords: [epinio, kubernetes, builder images] +doc-type: [how-to] +doc-topic: [epinio, how-to, builder images] +doc-persona: [epinio-developer, epinio-operator] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide explores working with builder images. Builder images transform source code into runnable container images. For more information see the [builder images reference](../../../../reference/customization/staging.md) page. + +## View Builder Images + + + + +To view all available builder images, navigate to the **Builder Images** page under the **Advanced** section of the side navigation menu. + +View of the Builder Images screen + + + + +List all known builder images: + +```console +epinio buildimage list +``` + +Show the details of a single builder image: + +```console +epinio buildimage show myimage +``` + + + + +## Create a Builder Image + + + + +Click **Create** on the Builder Images page to open the creation modal. Here you can provide a name, descriptions and the image itself. + +Create Builder Image Modal + + + + + +Create a builder image. Both `--name` and `--image` are required: + +```console +epinio buildimage create --name myimage \ + --image paketobuildpacks/builder-jammy-full:latest \ + --short-description "My builder image" \ + --description "A longer description of my builder image" +``` + + + + +## Edit a Builder Image + + + + +Select **Edit** from the action menu for the row of the builder image you wish to edit. Use caution when editing images that are being used by applications, as you may cause issues for future rebuilds. + +Edit Builder Image Modal + + + + + +Update a builder image. Flags you do not set leave the corresponding fields unchanged: + +```console +epinio buildimage update myimage \ + --image paketobuildpacks/builder-jammy-full:0.4.0 \ + --short-description "An updated description" +``` + + + + +## Delete a Builder Image + + + + +Open the action menu for the builder image and select **Delete**. Confirm the deletion. + +Delete Builder Image Modal + + + + + +Delete a builder image: + +```console +epinio buildimage delete myimage +``` + + + + + +## Additional CLI Commands +For additional documentation on the CLI commands above, along with additional commands, see the [epinio buildimage](../../../../reference/cli/buildimage/epinio_buildimage.md) CLI reference. \ No newline at end of file diff --git a/docs/how-to/developer/concepts/builder-images/builder-screen.png b/docs/how-to/developer/concepts/builder-images/builder-screen.png new file mode 100644 index 00000000000..c2d7819cb08 Binary files /dev/null and b/docs/how-to/developer/concepts/builder-images/builder-screen.png differ diff --git a/docs/how-to/developer/concepts/git-configs/git-configs-create-modal.png b/docs/how-to/developer/concepts/git-configs/git-configs-create-modal.png new file mode 100644 index 00000000000..495fcce8006 Binary files /dev/null and b/docs/how-to/developer/concepts/git-configs/git-configs-create-modal.png differ diff --git a/docs/how-to/developer/concepts/git-configs/git-configs-delete-modal.png b/docs/how-to/developer/concepts/git-configs/git-configs-delete-modal.png new file mode 100644 index 00000000000..20df76776fd Binary files /dev/null and b/docs/how-to/developer/concepts/git-configs/git-configs-delete-modal.png differ diff --git a/docs/how-to/developer/concepts/git-configs/git-configs-screen.png b/docs/how-to/developer/concepts/git-configs/git-configs-screen.png new file mode 100644 index 00000000000..3d1269e5986 Binary files /dev/null and b/docs/how-to/developer/concepts/git-configs/git-configs-screen.png differ diff --git a/docs/how-to/developer/concepts/git-configs/git-configs.mdx b/docs/how-to/developer/concepts/git-configs/git-configs.mdx new file mode 100644 index 00000000000..cb795bf59e5 --- /dev/null +++ b/docs/how-to/developer/concepts/git-configs/git-configs.mdx @@ -0,0 +1,108 @@ +--- +sidebar_label: Git Configurations +sidebar_position: 8 +title: Git Configurations +description: How to use Epinio git configurations. +keywords: [epinio, kubernetes, git configuartions] +doc-type: [how-to] +doc-topic: [epinio, how-to, git configurations] +doc-persona: [epinio-developer, epinio-operator] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide explores working with git configurations. Git configurations enable cloning of private repositories, disabling of SSL verification, and/or extending verification through a custom bundle of certificates. For more information see the [git configurations reference](../../../../reference/concepts/git_configuration.md) page. + +## View Git Configurations + + + + +To view all available git configurations, navigate to the **Git Configs** page under the **Advanced** section of the side navigation menu. + +View of the Git Configs screen + + + + +List all git configs: + +```console +epinio gitconfig list +``` + + + + +## Create a Git Configuration + + + + +Click **Create** on the Git Configs page to open the creation modal. First, you must provide a unique id for your git config. + +Epinio offers several git providers to choose from, including GitHub and GitLab. If you select enterprise versions of GitHub or GitLab, you will also have to provide the host URL. + +You can also provide your Git username, as well as a password/token, so Epinio can access private repos/projects. + +Finally, you can provide epinio with git certificates and toggle some addtional config options. + +Create Git Config Modal + + + + + +Create git config: + +```console +epinio gitconfig create github-epinio-example-go-configuration https://github.com \ + --git-provider github \ + --user-org epinio \ + --repository example-go \ + --skip-ssl \ + --username myuser \ + --password abcde12345 \ + --cert-file /path/to/some/certfile +``` + + + + +## Delete a Git Configuration + + + + +Open the action menu for the git config and select **Delete**. Confirm the deletion. + +Delete Git Config Modal + + + + + +Delete git config: + +```console +epinio gitconfig delete my-git-config +``` + + + + + +## Additional CLI Commands +For additional documentation on the CLI commands above, along with additional commands, see the [epinio gitconfig chart](../../../../reference/cli/gitconfig/epinio_gitconfig.md) CLI reference. \ No newline at end of file diff --git a/docs/how-to/developer/concepts/git_configuration.md b/docs/how-to/developer/concepts/git_configuration.md deleted file mode 100644 index 0223d438ddb..00000000000 --- a/docs/how-to/developer/concepts/git_configuration.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: Creating a Git configuration -sidebar_position: 13 -title: Creating a Git configuration -description: How to create a Git configuration -keywords: [epinio, kubernetes, git configuration] -doc-type: [how-to] -doc-topic: [epinio, how-to, customize, create-git-config] -doc-persona: [epinio-operator] ---- - - -As described -[in the Git Configuration reference page](../../../reference/concepts/git_configuration.md), -Epinio Git Configurations are Kubernetes secrets with a particular label. - -Creation is done with the -[epinio gitconfig create](../../../reference/cli/gitconfig/epinio_gitconfig_create.md) -command. - -For example: - -```console -epinio gitconfig create github-epinio-example-go-configuration https://github.com \ - --git-provider github \ - --user-org epinio \ - --repository example-go \ - --skip-ssl \ - --username myuser \ - --password abcde12345 \ - --cert-file /path/to/some/certfile -``` - -The only required arguments are the name of the git configuration, and the repository URL. -Everything else is optional, and specified through flags. - -If, for example, to skip the SSL configuration for a particular provider use: - -```bash -epinio gitconfig create mygit-config https://gitlab.mydomain.com --skip-ssl -``` diff --git a/docs/how-to/developer/concepts/service-catalog/catalog-screen.png b/docs/how-to/developer/concepts/service-catalog/catalog-screen.png index 2ec4648044c..1f5301fa62d 100644 Binary files a/docs/how-to/developer/concepts/service-catalog/catalog-screen.png and b/docs/how-to/developer/concepts/service-catalog/catalog-screen.png differ diff --git a/docs/how-to/developer/concepts/service-catalog/catalog-service-create-modal.png b/docs/how-to/developer/concepts/service-catalog/catalog-service-create-modal.png new file mode 100644 index 00000000000..176de98ac96 Binary files /dev/null and b/docs/how-to/developer/concepts/service-catalog/catalog-service-create-modal.png differ diff --git a/docs/how-to/developer/concepts/service-catalog/catalog-service-delete-modal.png b/docs/how-to/developer/concepts/service-catalog/catalog-service-delete-modal.png new file mode 100644 index 00000000000..b2a7a910763 Binary files /dev/null and b/docs/how-to/developer/concepts/service-catalog/catalog-service-delete-modal.png differ diff --git a/docs/how-to/developer/concepts/service-catalog/catalog-service-edit-modal.png b/docs/how-to/developer/concepts/service-catalog/catalog-service-edit-modal.png new file mode 100644 index 00000000000..8577eae50d3 Binary files /dev/null and b/docs/how-to/developer/concepts/service-catalog/catalog-service-edit-modal.png differ diff --git a/docs/how-to/developer/concepts/service-catalog/catalog-service-screen.png b/docs/how-to/developer/concepts/service-catalog/catalog-service-screen.png index 94d41c78197..736da190114 100644 Binary files a/docs/how-to/developer/concepts/service-catalog/catalog-service-screen.png and b/docs/how-to/developer/concepts/service-catalog/catalog-service-screen.png differ diff --git a/docs/how-to/developer/concepts/service-catalog/service-catalog.mdx b/docs/how-to/developer/concepts/service-catalog/service-catalog.mdx index a0127270193..cba813aa794 100644 --- a/docs/how-to/developer/concepts/service-catalog/service-catalog.mdx +++ b/docs/how-to/developer/concepts/service-catalog/service-catalog.mdx @@ -62,7 +62,112 @@ epinio service catalog myservice -### Service Catalog CRUD Coming Soon! +## Create a Catalog Service + + + + +Click **Create** on the Catalog page to open the creation modal. Here you can provide a name and descriptions used to identify the service. + +You can also provide an image url that will be used as the icon when displaying the service in the catalog. + +You will need to provide the name of the chart to install and can optionally provide the version of the chart and/or the version of the app packaged by the chart. Next, provide the information relating to the Helm repo where the chart lives. + +You can also add configurable settings that can be provided when provisioning the service. + +Under the Advanced Options you can tell Epinio what kinds of Kubernetes Secrets are compatible with the service. + +Create Catalog Service Modal + + + + + +Create a catalog service. Both `--name` and `--chart` are required: + +```console +epinio service catalog create --name mysql \ + --chart mysql \ + --chart-version 9.4.1 \ + --app-version 8.0.30 \ + --helm-repo-name bitnami \ + --helm-repo-url https://charts.bitnami.com/bitnami \ + --short-description "MySQL database" \ + --description "A MySQL database provisioned from the Bitnami chart" \ + --service-icon https://example.com/mysql.png \ + --secret-types "mysql,database" +``` + +Use `--values-file` to pass a YAML file with the settings that can be configured when provisioning the service: + +```console +epinio service catalog create --name mysql --chart mysql \ + --helm-repo-url https://charts.bitnami.com/bitnami \ + --values-file ./mysql-values.yaml +``` + +If the Helm repository requires credentials, reference the secret holding them with `--helm-repo-secret`. + + + + +## Edit a Catalog Service + + + + +Select **Edit** from the action menu from the card of the catalog service you wish to edit. You can also open the edit modal from the details page. Use caution when editing catalog services when there are associated service instances. + +Edit Catalog Service Modal + + + + + +Update a catalog service. Flags you do not set leave the corresponding fields unchanged: + +```console +epinio service catalog update mysql \ + --chart-version 9.5.0 \ + --short-description "An updated description" +``` + + + + +## Delete a Catalog Service + + + + +Open the action menu for the catalog service and select **Delete**. Confirm the deletion. This can also be done from the details page + +Delete Catalog Service Modal + + + + + +Delete a catalog service: + +```console +epinio service catalog delete mysql +``` + + + ## Additional CLI Commands -For additional documentation on the CLI commands above, along with additional commands, see the [epinio service catalog](../../../../reference/cli/service/epinio_service_catalog.md) CLI reference. \ No newline at end of file +For additional documentation on the CLI commands above, along with additional commands, see the [epinio service catalog](../../../../reference/cli/service/catalog/epinio_service_catalog.md) CLI reference. \ No newline at end of file diff --git a/docs/how-to/operator/customization/create_custom_appcharts.md b/docs/how-to/operator/customization/create_custom_appcharts.md index b35752760a0..6ff33e08106 100644 --- a/docs/how-to/operator/customization/create_custom_appcharts.md +++ b/docs/how-to/operator/customization/create_custom_appcharts.md @@ -163,6 +163,22 @@ You can also see the details of the chart in Epinio: epinio app chart show fluentd ``` +:::tip + +Instead of applying the custom resource with `kubectl`, you can register the chart directly with Epinio: + +```console +epinio app chart create --name fluentd \ + --short-description "Fluentd filterable standard deployment" \ + --description "Epinio standard support chart extended for fluentd filtering" \ + --helm-chart https://mydomain.org/epinio-application-fluentd.tgz +``` + +The same can be done from the **Application Charts** page in the web UI. +See the [app charts how-to](../../developer/concepts/app-charts/app-charts.mdx) for details. + +::: + ### User-settable configuration values To expose the user-settable configuration value `foo` the created application chart has to look for this variable in the `.Values.userConfig` map. diff --git a/docs/how-to/operator/customization/create_custom_service.md b/docs/how-to/operator/customization/create_custom_service.md index 6e5e31b516e..f4d072d88bf 100644 --- a/docs/how-to/operator/customization/create_custom_service.md +++ b/docs/how-to/operator/customization/create_custom_service.md @@ -40,6 +40,23 @@ If everything worked correctly, you can see your Service in the Epinio `service- epinio service catalog ``` +:::tip + +Instead of applying the custom resource with `kubectl`, you can create the catalog service directly with Epinio: + +```console +epinio service catalog create --name mysql-custom \ + --chart mysql \ + --helm-repo-name bitnami \ + --helm-repo-url https://charts.bitnami.com/bitnami \ + --short-description "MySQL database" +``` + +The same can be done from the **Catalog** page in the web UI. +See the [service catalog how-to](../../developer/concepts/service-catalog/service-catalog.mdx) for details. + +::: + ## Adding an Image to the service The consumers of the API (that is, the web UI of Epinio) can show an icon when listing the available services. diff --git a/docs/how-to/operator/customization/custom_builder.md b/docs/how-to/operator/customization/custom_builder.md index 20e7134b2e8..2356f5e1807 100644 --- a/docs/how-to/operator/customization/custom_builder.md +++ b/docs/how-to/operator/customization/custom_builder.md @@ -97,6 +97,18 @@ You can then push your application to Epinio and use your image with the `--buil epinio push -n myapp -p app_directory --builder-image myorg/epicustombuilder:latest ``` +Alternatively, register the image with Epinio so it's offered to your developers as a choice when +they create an application: + +```console +epinio buildimage create --name epicustombuilder \ + --image myorg/epicustombuilder:latest \ + --short-description "Custom builder with Python support" +``` + +The same can be done from the **Builder Images** page in the web UI. +See the [builder images how-to](../../developer/concepts/builder-images/builder-images.mdx) for details. + ## More examples You can find a more complete example on how to build and deploy a custom builder at diff --git a/docs/how-to/operator/networking/enable_gateway_api.md b/docs/how-to/operator/networking/enable_gateway_api.md new file mode 100644 index 00000000000..3c3bf6cb7a8 --- /dev/null +++ b/docs/how-to/operator/networking/enable_gateway_api.md @@ -0,0 +1,133 @@ +--- +sidebar_label: Gateway API +sidebar_position: 1 +title: Epinio with Gateway API +description: How to set up and use the Gateway API with Epinio +keywords: [epinio, gateway, api] +doc-type: [how-to] +doc-topic: [epinio, how-to, gateway-api] +doc-persona: [epinio-developer, epinio-operator] +--- + +# Epinio with Gateway API + +Gateway API is now supported by Epinio as an alternative to Ingress that also coincides with the EOL of Ingress NGINX. If you are asking yourself why you should make the switch, we will refer you to official Kubernetes documentation on [Reasons to Switch to Gateway API](https://gateway-api.sigs.k8s.io/guides/getting-started/migrating-from-ingress/#reasons-to-switch-to-gateway-api). + +## Prerequisites + +### Gateway Controller + +Before configuring Epinio to leverage Gateway API, you need a **Gateway Controller**. There are several options to consider, to name a couple: + +- [Traefik Gateway API](https://doc.traefik.io/traefik/reference/install-configuration/providers/kubernetes/kubernetes-gateway/) +- [Cilium Gateway API (w/ Envoy)](https://docs.cilium.io/en/latest/network/servicemesh/gateway-api/gateway-api/) + +You will be able to install one or several options with **Helm**, supplying values to opt-in to their Gateway API support. Once you have followed and completed their setup instructions, you will then be able to leverage pertinent **Custom Resource Definitions**, for example: `Gateway`, `HTTPRoute`, and `TCPRoute`. **Epinio** simplifies the deployment of these custom resource definitions via the chart's values interface. + + +### Knowledge of Epinio Installation + +For simplification purposes of this walkthrough, we assume that you know how to install and configure Epinio already. If you do not already have a firm grasp on this process, please refer to our existing [documentation](https://docs.epinio.io/installation/install_epinio). + + +## Setup Gateway API + +For walkthrough purposes, we'll utilize **Traefik**. + +1. Install Gateway API CRDs + +```bash +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml +``` + +2. Install Traefik RBAC for Gateway API + +```bash +kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml +``` + +3. Install **Traefik** with Gateway API configs: + +```bash +helm repo add traefik https://traefik.github.io/charts +helm repo update +helm install traefik traefik/traefik \ + --namespace traefik \ + --create-namespace \ + --set providers.kubernetesGateway.enabled=true +``` + +We will now have the necessary `GatewayClass` CRD deployed to our cluster. + + +## Install Epinio's Gateway API Resources + +Update your Helm values to leverage Epinio's Gateway API resources, simply: + +- `Gateway` + +```yaml +## --set gateway.enabled=true +gateway: + enabled: true +``` + +- `HTTPRoute` + +```yaml +## --set httpRoute.enabled=true +httpRoute: + enabled: true +``` + +- Domain name + +```yaml +## --set global.domain=127.0.0.1.sslip.io +global: + domain: 127.0.0.1.sslip.io +``` + +❗**IMPORTANT**: + +We allow the existence of both Ingress & Gateway API resources to facilitate migration efforts in dev/qa. **However**, we advise that you practice one implementation in production. If you have enabled your Gateway API resources, disable Ingress resources by setting: + +```yaml +## --set ingress.enabled=false +ingress: + enabled: false +``` + +Once these Helm values have been applied to your installation via `helm upgrade --install`, your `Gateway` and `HTTPRoute` resources will be deployed to the cluster, ready to handle incoming traffic. + + +### Additional Configuration + +There are additional configurations to control the behavior for Epinio's usage of Gateway API. + +- `gateway.hostnameOverride` & `gateway.dexHostnameOverride` + - Configurable values to override the defaults determined by `global.domain` +- `gateway.gatewayClassName` + - Determines the Gateway Controller's class that we wish to use. For this walkthrough, we installed Traefik, thus our class name is `traefik` which happens to be the default. +- `gateway.tls.enabled` + - Determines whether or not we secure traffic to Epinio with an HTTPS redirect within Kubernetes at the Gateway. In order to enable an HTTPS redirect, set to `true`. **Required for the Epinio UI to function** without it the gateway has no HTTPS listener and the browser/cli will block login requests with a null-status CORS error. +- `gateway.annotations` & `httpRoute.annotations` + - Provide any annotations necessary for your custom implementations, such as certificate issuers. + +There are more configurations available however these are the most relevant and anticipated for customization. + + +## Verify Functionality + +You should be able to visit `https://epinio.` and reach Epinio (note the `epinio.` subdomain prefix, not the bare domain). If not, there are individual items to troubleshoot: + +1. Does my **Gateway Controller's** `LoadBalancer` service have an **External IP**? Verify a value is provided in the `External-IP` column. + +```bash +kubectl get svc +``` + +2. Can I reach the **External IP** of the **Gateway Controller's** `Loadbalancer` service? + +3. Is my domain configured properly via **Epinio** values? Is DNS configured appropriately for the domain and IP address? + diff --git a/docs/reference/cli/app/chart/epinio_app_chart.md b/docs/reference/cli/app/chart/epinio_app_chart.md index 00c6bf12688..04ac3e7e5e7 100644 --- a/docs/reference/cli/app/chart/epinio_app_chart.md +++ b/docs/reference/cli/app/chart/epinio_app_chart.md @@ -39,7 +39,10 @@ Manage epinio application charts ### SEE ALSO * [epinio app](../epinio_app.md) - Epinio application features +* [epinio app chart create](./epinio_app_chart_create.md) - Create an application chart * [epinio app chart default](./epinio_app_chart_default.md) - Set or show app chart default +* [epinio app chart delete](./epinio_app_chart_delete.md) - Delete an application chart * [epinio app chart list](./epinio_app_chart_list.md) - List application charts * [epinio app chart show](./epinio_app_chart_show.md) - Describe application chart +* [epinio app chart update](./epinio_app_chart_update.md) - Update an application chart diff --git a/docs/reference/cli/app/chart/epinio_app_chart_create.md b/docs/reference/cli/app/chart/epinio_app_chart_create.md new file mode 100644 index 00000000000..655450325b0 --- /dev/null +++ b/docs/reference/cli/app/chart/epinio_app_chart_create.md @@ -0,0 +1,50 @@ +--- +sidebar_label: epinio app chart create +title: "" +description: epinio app chart create +keywords: [epinio, kubernetes, epinio app chart create] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-app-chart-create] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio app chart create + +Create an application chart + +### Synopsis + +Create an application chart + +``` +epinio app chart create --name NAME [flags] +``` + +### Options + +``` + --description string long description + --helm-chart string Helm chart URL + --helm-repo string Helm repository URL + -h, --help help for create + --name string application chart name (required) + --set strings values map entry as key=value (repeatable) + --short-description string short description +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio app chart](./epinio_app_chart.md) - Epinio application chart management + diff --git a/docs/reference/cli/app/chart/epinio_app_chart_delete.md b/docs/reference/cli/app/chart/epinio_app_chart_delete.md new file mode 100644 index 00000000000..23f90f5d5a2 --- /dev/null +++ b/docs/reference/cli/app/chart/epinio_app_chart_delete.md @@ -0,0 +1,40 @@ +--- +sidebar_label: epinio app chart delete +title: "" +description: epinio app chart delete +keywords: [epinio, kubernetes, epinio app chart delete] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-app-chart-delete] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio app chart delete + +Delete an application chart + +``` +epinio app chart delete NAME [flags] +``` + +### Options + +``` + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio app chart](./epinio_app_chart.md) - Epinio application chart management + diff --git a/docs/reference/cli/app/chart/epinio_app_chart_update.md b/docs/reference/cli/app/chart/epinio_app_chart_update.md new file mode 100644 index 00000000000..438f0998d48 --- /dev/null +++ b/docs/reference/cli/app/chart/epinio_app_chart_update.md @@ -0,0 +1,49 @@ +--- +sidebar_label: epinio app chart update +title: "" +description: epinio app chart update +keywords: [epinio, kubernetes, epinio app chart update] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-app-chart-update] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio app chart update + +Update an application chart + +### Synopsis + +Update an application chart. Unset flags leave the corresponding fields unchanged. + +``` +epinio app chart update NAME [flags] +``` + +### Options + +``` + --description string long description + --helm-chart string Helm chart URL + --helm-repo string Helm repository URL + -h, --help help for update + --set strings values map entry as key=value (repeatable) + --short-description string short description +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio app chart](./epinio_app_chart.md) - Epinio application chart management + diff --git a/docs/reference/cli/app/epinio_app.md b/docs/reference/cli/app/epinio_app.md index 5612cd8f889..5122a5c2ff9 100644 --- a/docs/reference/cli/app/epinio_app.md +++ b/docs/reference/cli/app/epinio_app.md @@ -58,4 +58,4 @@ epinio app [flags] * [epinio app restart](./epinio_app_restart.md) - Restart the application * [epinio app show](./epinio_app_show.md) - Describe the named application * [epinio app update](./epinio_app_update.md) - Update the named application - +* [epinio app watch](./epinio_app_watch.md) - Watch a local directory and sync changes to the running application diff --git a/docs/reference/cli/app/.epinio_app_watch.md b/docs/reference/cli/app/epinio_app_watch.md similarity index 78% rename from docs/reference/cli/app/.epinio_app_watch.md rename to docs/reference/cli/app/epinio_app_watch.md index 03d60f19340..c63d97b1015 100644 --- a/docs/reference/cli/app/.epinio_app_watch.md +++ b/docs/reference/cli/app/epinio_app_watch.md @@ -7,6 +7,13 @@ doc-type: [reference] doc-topic: [epinio, reference, epinio-cli, epinio-app-watch] doc-persona: [epinio-developer] --- + +:::caution Experimental +app watch is experimental: it has been validate on a limited set of frameworks +and builder iamges. Behavior on other app types and binary layouts is not yet +guaranteed. +::: + ## epinio app watch Watch a local directory and sync changes to the running application @@ -19,10 +26,11 @@ epinio app watch NAME [flags] Watches the source directory for changes and syncs them into the running pod. -On the first run (no local state file) a full buildpack push is performed and -the running deployment is patched with a supervisor wrapper. On subsequent runs -only changed files or the rebuilt binary are uploaded via the Epinio API, -without going through the buildpack pipeline. +On startup a full buildpack push is performed and the running deployment is +patched with a supervisor wrapper. This happens on every `app watch` run so the +supervisor is always re-established, even after a plain `epinio app push`. While +watching, only changed files or the rebuilt binary are uploaded via the Epinio +API, without going through the buildpack pipeline. Configure binary mode (compiled languages) or override sync paths by placing an `.epinio-sync.yaml` file in the source directory. diff --git a/docs/reference/cli/buildimage/_category_.json b/docs/reference/cli/buildimage/_category_.json new file mode 100644 index 00000000000..d7472401a15 --- /dev/null +++ b/docs/reference/cli/buildimage/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "epinio buildimage", + "collapsed": true, + "link": { + "type": "doc", + "id": "reference/cli/buildimage/epinio_buildimage" + } +} diff --git a/docs/reference/cli/buildimage/epinio_buildimage.md b/docs/reference/cli/buildimage/epinio_buildimage.md new file mode 100644 index 00000000000..4862ae723c6 --- /dev/null +++ b/docs/reference/cli/buildimage/epinio_buildimage.md @@ -0,0 +1,45 @@ +--- +sidebar_label: epinio buildimage +title: "" +description: epinio buildimage +keywords: [epinio, kubernetes, epinio buildimage] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-buildimage] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio buildimage + +Epinio builder image management + +### Synopsis + +Manage epinio builder images + +### Options + +``` + -h, --help help for buildimage +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio](../epinio.md) - Epinio cli +* [epinio buildimage create](./epinio_buildimage_create.md) - Create a builder image +* [epinio buildimage delete](./epinio_buildimage_delete.md) - Delete a builder image +* [epinio buildimage list](./epinio_buildimage_list.md) - List builder images +* [epinio buildimage show](./epinio_buildimage_show.md) - Describe a builder image +* [epinio buildimage update](./epinio_buildimage_update.md) - Update a builder image + diff --git a/docs/reference/cli/buildimage/epinio_buildimage_create.md b/docs/reference/cli/buildimage/epinio_buildimage_create.md new file mode 100644 index 00000000000..29cffebb7cb --- /dev/null +++ b/docs/reference/cli/buildimage/epinio_buildimage_create.md @@ -0,0 +1,48 @@ +--- +sidebar_label: epinio buildimage create +title: "" +description: epinio buildimage create +keywords: [epinio, kubernetes, epinio buildimage create] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-buildimage-create] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio buildimage create + +Create a builder image + +### Synopsis + +Create a builder image + +``` +epinio buildimage create --name NAME --image IMAGE [flags] +``` + +### Options + +``` + --description string long description + -h, --help help for create + --image string full image reference + --name string builder image name (required) + --short-description string short description +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio buildimage](./epinio_buildimage.md) - Epinio builder image management + diff --git a/docs/reference/cli/buildimage/epinio_buildimage_delete.md b/docs/reference/cli/buildimage/epinio_buildimage_delete.md new file mode 100644 index 00000000000..69416fedfa3 --- /dev/null +++ b/docs/reference/cli/buildimage/epinio_buildimage_delete.md @@ -0,0 +1,44 @@ +--- +sidebar_label: epinio buildimage delete +title: "" +description: epinio buildimage delete +keywords: [epinio, kubernetes, epinio buildimage delete] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-buildimage-delete] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio buildimage delete + +Delete a builder image + +### Synopsis + +Delete a builder image + +``` +epinio buildimage delete NAME [flags] +``` + +### Options + +``` + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio buildimage](./epinio_buildimage.md) - Epinio builder image management + diff --git a/docs/reference/cli/buildimage/epinio_buildimage_list.md b/docs/reference/cli/buildimage/epinio_buildimage_list.md new file mode 100644 index 00000000000..81a5bf44b84 --- /dev/null +++ b/docs/reference/cli/buildimage/epinio_buildimage_list.md @@ -0,0 +1,44 @@ +--- +sidebar_label: epinio buildimage list +title: "" +description: epinio buildimage list +keywords: [epinio, kubernetes, epinio buildimage list] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-buildimage-list] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio buildimage list + +List builder images + +### Synopsis + +List all known builder images + +``` +epinio buildimage list [flags] +``` + +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio buildimage](./epinio_buildimage.md) - Epinio builder image management + diff --git a/docs/reference/cli/buildimage/epinio_buildimage_show.md b/docs/reference/cli/buildimage/epinio_buildimage_show.md new file mode 100644 index 00000000000..9be8a9eaeb3 --- /dev/null +++ b/docs/reference/cli/buildimage/epinio_buildimage_show.md @@ -0,0 +1,44 @@ +--- +sidebar_label: epinio buildimage show +title: "" +description: epinio buildimage show +keywords: [epinio, kubernetes, epinio buildimage show] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-buildimage-show] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio buildimage show + +Describe a builder image + +### Synopsis + +Show the details of the named builder image + +``` +epinio buildimage show NAME [flags] +``` + +### Options + +``` + -h, --help help for show +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio buildimage](./epinio_buildimage.md) - Epinio builder image management + diff --git a/docs/reference/cli/buildimage/epinio_buildimage_update.md b/docs/reference/cli/buildimage/epinio_buildimage_update.md new file mode 100644 index 00000000000..532e6b9ca4e --- /dev/null +++ b/docs/reference/cli/buildimage/epinio_buildimage_update.md @@ -0,0 +1,47 @@ +--- +sidebar_label: epinio buildimage update +title: "" +description: epinio buildimage update +keywords: [epinio, kubernetes, epinio buildimage update] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-buildimage-update] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio buildimage update + +Update a builder image + +### Synopsis + +Update a builder image. Unset flags leave the corresponding fields unchanged. + +``` +epinio buildimage update NAME [flags] +``` + +### Options + +``` + --description string long description + -h, --help help for update + --image string full image reference + --short-description string short description +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio buildimage](./epinio_buildimage.md) - Epinio builder image management + diff --git a/docs/reference/cli/epinio.md b/docs/reference/cli/epinio.md index 1b6c38258ee..ca433156ff2 100644 --- a/docs/reference/cli/epinio.md +++ b/docs/reference/cli/epinio.md @@ -34,6 +34,7 @@ epinio cli is the official command line interface for Epinio PaaS ### SEE ALSO * [epinio app](./app/epinio_app.md) - Epinio application features +* [epinio buildimage](./buildimage/epinio_buildimage.md) - Epinio builder image management * [epinio client-sync](./epinio_client-sync.md) - Downloads a client binary matching the currently logged server * [epinio completion](./epinio_completion.md) - Generate completion script for a shell * [epinio configuration](./configuration/epinio_configuration.md) - Epinio configuration features diff --git a/docs/reference/cli/epinio_server.md b/docs/reference/cli/epinio_server.md index eec23d73c5f..7534f60c204 100644 --- a/docs/reference/cli/epinio_server.md +++ b/docs/reference/cli/epinio_server.md @@ -28,6 +28,7 @@ epinio server [flags] --disable-tracking (DISABLE_TRACKING) Disable tracking of the running Epinio and Kubernetes versions -h, --help help for server --ingress-class-name string (INGRESS_CLASS_NAME) Name of the ingress class to use for apps. Leave empty to add no ingressClassName to the ingress. + --gateway-class-name string (GATEWAY_CLASS_NAME) Name of the gateway class to use for apps. Leave empty to add no gatewayClassName to the gateway. --kube-api-burst int (KUBE_API_BURST) Maximum burst for throttle of the Kubernetes client. (default 10) --kube-api-qps float32 (KUBE_API_QPS) The QPS indicates the maximum QPS of the Kubernetes client. (default 5) -n, --namespace string (NAMESPACE) The namespace to use (default "epinio") diff --git a/docs/reference/cli/gitconfig/epinio_gitconfig_create.md b/docs/reference/cli/gitconfig/epinio_gitconfig_create.md index 8b8c90531a6..73de227a6cb 100644 --- a/docs/reference/cli/gitconfig/epinio_gitconfig_create.md +++ b/docs/reference/cli/gitconfig/epinio_gitconfig_create.md @@ -20,6 +20,7 @@ epinio gitconfig create ID URL [flags] ``` --cert-file string path to file holding supporting certificates --git-provider string Git provider code [git|github|github_enterprise|gitlab|gitlab_enterprise] (default "git") + --global make the configuration available to all users -h, --help help for create --password string password for logging into the host --repository string specific repository diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 89059710ee6..84fb48bd4d5 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -41,6 +41,20 @@ If you have not installed the CLI yet, start with | [`epinio app port-forward`](./app/epinio_app_port-forward.md) | Forward a local port to an application | | [`epinio app env`](./app/env/epinio_app_env.md) | Manage application environment variables | | [`epinio app chart`](./app/chart/epinio_app_chart.md) | Inspect and select application charts | +| [`epinio app chart create`](./app/chart/epinio_app_chart_create.md) | Create an application chart | +| [`epinio app chart update`](./app/chart/epinio_app_chart_update.md) | Update an application chart | +| [`epinio app chart delete`](./app/chart/epinio_app_chart_delete.md) | Delete an application chart | + +## Builder images + +| Command | What it does | +| --- | --- | +| [`epinio buildimage`](./buildimage/epinio_buildimage.md) | Top-level command for builder image management | +| [`epinio buildimage list`](./buildimage/epinio_buildimage_list.md) | List builder images | +| [`epinio buildimage show`](./buildimage/epinio_buildimage_show.md) | Describe a builder image | +| [`epinio buildimage create`](./buildimage/epinio_buildimage_create.md) | Create a builder image | +| [`epinio buildimage update`](./buildimage/epinio_buildimage_update.md) | Update a builder image | +| [`epinio buildimage delete`](./buildimage/epinio_buildimage_delete.md) | Delete a builder image | ## Configurations @@ -56,7 +70,10 @@ If you have not installed the CLI yet, start with | Command | What it does | | --- | --- | | [`epinio service`](./service/epinio_service.md) | Top-level command for service management | -| [`epinio service catalog`](./service/epinio_service_catalog.md) | Browse the service catalog | +| [`epinio service catalog`](./service/catalog/epinio_service_catalog.md) | Browse the service catalog | +| [`epinio service catalog create`](./service/catalog/epinio_service_catalog_create.md) | Create a catalog service | +| [`epinio service catalog update`](./service/catalog/epinio_service_catalog_update.md) | Update a catalog service | +| [`epinio service catalog delete`](./service/catalog/epinio_service_catalog_delete.md) | Delete a catalog service | | [`epinio service create`](./service/epinio_service_create.md) | Provision a service from the catalog | | [`epinio service bind`](./service/epinio_service_bind.md) | Bind a service to an application | diff --git a/docs/reference/cli/service/catalog/_category_.json b/docs/reference/cli/service/catalog/_category_.json new file mode 100644 index 00000000000..16c8fa00327 --- /dev/null +++ b/docs/reference/cli/service/catalog/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "epinio service catalog", + "collapsed": true, + "link": { + "type": "doc", + "id": "reference/cli/service/catalog/epinio_service_catalog" + } +} diff --git a/docs/reference/cli/service/epinio_service_catalog.md b/docs/reference/cli/service/catalog/epinio_service_catalog.md similarity index 69% rename from docs/reference/cli/service/epinio_service_catalog.md rename to docs/reference/cli/service/catalog/epinio_service_catalog.md index 7c876b3c375..f1c490ed132 100644 --- a/docs/reference/cli/service/epinio_service_catalog.md +++ b/docs/reference/cli/service/catalog/epinio_service_catalog.md @@ -26,17 +26,18 @@ epinio service catalog [NAME] [flags] ``` -H, --header stringArray Add custom header to every request executed -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") --no-colors Suppress colorized output --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) - --trace-file string (TRACE_FILE) Print trace messages to the specified file - --trace-level int (TRACE_LEVEL) Only print trace messages at or above this level (0 to 255, default 0, print nothing) - --trace-output string (TRACE_OUTPUT) Sets trace output format [text,json] (default "text") --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) ``` ### SEE ALSO -* [epinio service](./epinio_service.md) - Epinio service management +* [epinio service](../epinio_service.md) - Epinio service management +* [epinio service catalog create](./epinio_service_catalog_create.md) - Create an Epinio catalog service +* [epinio service catalog delete](./epinio_service_catalog_delete.md) - Delete an Epinio catalog service +* [epinio service catalog update](./epinio_service_catalog_update.md) - Update an Epinio catalog service diff --git a/docs/reference/cli/service/catalog/epinio_service_catalog_create.md b/docs/reference/cli/service/catalog/epinio_service_catalog_create.md new file mode 100644 index 00000000000..f3f398625d0 --- /dev/null +++ b/docs/reference/cli/service/catalog/epinio_service_catalog_create.md @@ -0,0 +1,52 @@ +--- +sidebar_label: epinio service catalog create +title: "" +description: epinio service catalog create +keywords: [epinio, kubernetes, epinio service catalog create] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-service-catalog-create] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio service catalog create + +Create an Epinio catalog service + +``` +epinio service catalog create --name NAME --chart CHART [flags] +``` + +### Options + +``` + --app-version string application version + --chart string Helm chart + --chart-version string Helm chart version + --description string long description + --helm-repo-name string Helm repository name + --helm-repo-secret string Helm repository credentials secret + --helm-repo-url string Helm repository URL + -h, --help help for create + --name string catalog service name (required) + --secret-types strings comma-separated secret types + --service-icon string service icon + --short-description string short description + --values-file string path to a YAML file whose contents are sent as the values string field +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio service catalog](./epinio_service_catalog.md) - Lists all available Epinio catalog services, or show the details of the specified one + diff --git a/docs/reference/cli/service/catalog/epinio_service_catalog_delete.md b/docs/reference/cli/service/catalog/epinio_service_catalog_delete.md new file mode 100644 index 00000000000..58b4d8f9551 --- /dev/null +++ b/docs/reference/cli/service/catalog/epinio_service_catalog_delete.md @@ -0,0 +1,40 @@ +--- +sidebar_label: epinio service catalog delete +title: "" +description: epinio service catalog delete +keywords: [epinio, kubernetes, epinio service catalog delete] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-service-catalog-delete] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio service catalog delete + +Delete an Epinio catalog service + +``` +epinio service catalog delete NAME [flags] +``` + +### Options + +``` + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio service catalog](./epinio_service_catalog.md) - Lists all available Epinio catalog services, or show the details of the specified one + diff --git a/docs/reference/cli/service/catalog/epinio_service_catalog_update.md b/docs/reference/cli/service/catalog/epinio_service_catalog_update.md new file mode 100644 index 00000000000..bdf3d417e78 --- /dev/null +++ b/docs/reference/cli/service/catalog/epinio_service_catalog_update.md @@ -0,0 +1,51 @@ +--- +sidebar_label: epinio service catalog update +title: "" +description: epinio service catalog update +keywords: [epinio, kubernetes, epinio service catalog update] +doc-type: [reference] +doc-topic: [epinio, reference, epinio-cli, epinio-service-catalog-update] +doc-persona: [epinio-developer, epinio-operator] +--- +## epinio service catalog update + +Update an Epinio catalog service + +``` +epinio service catalog update NAME [flags] +``` + +### Options + +``` + --app-version string application version + --chart string Helm chart + --chart-version string Helm chart version + --description string long description + --helm-repo-name string Helm repository name + --helm-repo-secret string Helm repository credentials secret + --helm-repo-url string Helm repository URL + -h, --help help for update + --secret-types strings comma-separated secret types + --service-icon string service icon + --short-description string short description + --values-file string path to a YAML file whose contents are sent as the values string field +``` + +### Options inherited from parent commands + +``` + -H, --header stringArray Add custom header to every request executed + -c, --kubeconfig string (KUBECONFIG) path to a kubeconfig, not required in-cluster + --log-level string (LOG_LEVEL) Only prints log messages at or above this level (debug, info, warn, error, fatal) (default "info") + --no-colors Suppress colorized output + --settings-file string (EPINIO_SETTINGS) set path of settings file (default "~/.config/epinio/settings.yaml") + --skip-ssl-verification (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates + --timeout-multiplier int (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1) + --verbosity int (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0) +``` + +### SEE ALSO + +* [epinio service catalog](./epinio_service_catalog.md) - Lists all available Epinio catalog services, or show the details of the specified one + diff --git a/docs/reference/cli/service/epinio_service.md b/docs/reference/cli/service/epinio_service.md index d4986957d57..87397d76959 100644 --- a/docs/reference/cli/service/epinio_service.md +++ b/docs/reference/cli/service/epinio_service.md @@ -44,7 +44,7 @@ epinio service [flags] * [epinio](../epinio.md) - Epinio cli * [epinio service bind](./epinio_service_bind.md) - Bind a service SERVICENAME to an Epinio app APPNAME -* [epinio service catalog](./epinio_service_catalog.md) - Lists all available Epinio catalog services, or show the details of the specified one +* [epinio service catalog](./catalog/epinio_service_catalog.md) - Lists all available Epinio catalog services, or show the details of the specified one * [epinio service create](./epinio_service_create.md) - Create a service SERVICENAME of an Epinio catalog service CATALOGSERVICENAME * [epinio service delete](./epinio_service_delete.md) - Delete one or more services * [epinio service list](./epinio_service_list.md) - List all the services in the targeted namespace diff --git a/docs/reference/concepts/_category_.json b/docs/reference/concepts/_category_.json index f46e44eeb25..e22fb3427a6 100644 --- a/docs/reference/concepts/_category_.json +++ b/docs/reference/concepts/_category_.json @@ -1 +1 @@ -{ "label": "Concepts", "position": 4, "collapsed": true } +{ "label": "Concepts", "position": 8, "collapsed": true } diff --git a/docs/reference/concepts/git-config-flow.png b/docs/reference/concepts/git-config-flow.png new file mode 100644 index 00000000000..584278967fd Binary files /dev/null and b/docs/reference/concepts/git-config-flow.png differ diff --git a/docs/reference/concepts/git_configuration.md b/docs/reference/concepts/git_configuration.md index b5ce0a00ff5..b5800ca499e 100644 --- a/docs/reference/concepts/git_configuration.md +++ b/docs/reference/concepts/git_configuration.md @@ -11,32 +11,25 @@ doc-topic: [epinio, reference, concepts, git-configuration] ## Overview -Starting with version **1.10.0**, Epinio supports Git configurations. - Configurations enable cloning of private repositories, disabling of SSL verification, and/or extending verification through a custom bundle of certificates. -This is done on a per git host (+user/org, +repository) basis. - -Management, including creation, is done through the -[epinio gitconfig](../cli/gitconfig/epinio_gitconfig.md) -command ensemble. - -## Matching process +For GitHub and GitLab instances you create a git configuration with a username and +password/token, and optionally the skip-SSL-verification and global flags. A **global** +configuration can be used by any user; a non-global one is visible and usable only to the user who +created it and to administrators. Only administrators may create a global configuration. -When importing from a git repository Epinio will use the most specific matching configuration, if -there is any. +For the `git`, GitHub Enterprise (Cloud and Self-Hosted), and GitLab Enterprise types the same +fields are available plus a **git host** field, where you enter the instance URL. -This means that a matching configuration specifying url, user/organization, and repository has -priority over matching configurations specifying only url and user/organization, or even just the -url. +You attach a configuration to an application by **selecting it** when you set the application's Git +source. Epinio does not implicitly match a configuration to a repository URL; the selection is +explicit, and a private repository will fail to clone if no usable configuration is selected. -If no configuration is found then the cloning from the Git repository will run without any -customization. -## Github/Gitlab specialities +## Github/Gitlab Specialities -The public Github and Gitlab mega repositories support the use of a `PAT` (Personal Access Token) +The public Github and Gitlab repositories support the use of a `PAT` (Personal Access Token) over a plain combination of user and password. When using a PAT it has to be set as the password, and the user can be set to anything except empty. @@ -45,76 +38,52 @@ When using a PAT it has to be set as the password, and the user can be set to an For reference, it is useful to set it to the username used to generate the token. ::: -## Detailed specification +## Enterprise and self-hosted instances -:::note -This section contains information useful to operators for debugging and inspection. -Regular users should not normally need to consult this section. -::: +The enterprise and generic `git` types take a **git host** URL in addition to the credential +fields: + +- **GitHub Enterprise Self-Hosted** (`github_enterprise_self_hosted`): enter the instance host URL + (for example `https://github.mycorp.com`). Epinio appends the GitHub Enterprise Server REST path + (`/api/v3`). +- **GitHub Enterprise Cloud** (`github_enterprise_cloud`): enter the API host URL for your + Enterprise Cloud instance, for example `https://api.github.com`, or `https://api..ghe.com` + for a data-residency instance. Epinio uses it as given. +- **GitLab Enterprise** (`gitlab_enterprise`) and generic **Git** (`git`): enter the instance host + URL. GitLab is accessed under `/api/v4`. + +## Detailed Specification A Git configuration is a Kubernetes secret with the `epinio.io/api-git-credentials: "true"` label. The fields are: -|Field |Required|Meaning | -|--- |--- |--- | -|`url` |yes | the host of the git instance | -|`provider` | | one of `github`, `gitlab`, `git`, `github_enterprise`, `gitlab_enterprise` | -|`username` | | used during the Basic Authentication | -|`password` | | used during the Basic Authentication | -|`userOrg` | | used to restrict the configuration to a specific organization/project | -|`repo` | | used to restrict the configuration to a specific repository | -|`skipSSL` | | used to skip the SSL verification | -|`certificate` | | the CA bundle to load for the SSL verification with self-signed certificates | - -All the fields, except for the URL, are optional. - -## Example: - -Invoking the commands - -```bash -cat > certfile < + +For more examples check the [How-to](../../how-to/developer/concepts/git-configs). diff --git a/docs/reference/customization/_category_.json b/docs/reference/customization/_category_.json index 27e3404da19..002554ab3a3 100644 --- a/docs/reference/customization/_category_.json +++ b/docs/reference/customization/_category_.json @@ -1 +1 @@ -{ "label": "Customization", "position": 5, "collapsed": true } +{ "label": "Customization", "position": 9, "collapsed": true } diff --git a/docs/reference/detailed-push-process.md b/docs/reference/detailed-push-process.md index 62ae3b62174..b9f212b58c0 100644 --- a/docs/reference/detailed-push-process.md +++ b/docs/reference/detailed-push-process.md @@ -1,5 +1,6 @@ --- sidebar_label: "Epinio push process" +sidebar_position: 6 title: "The Epinio push process in detail" description: The Epinio push process in detail keywords: [epinio, kubernetes, push process] diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md index df773611ca1..61ed527cd0b 100644 --- a/docs/reference/mcp.md +++ b/docs/reference/mcp.md @@ -2,7 +2,7 @@ sidebar_label: "MCP Server" sidebar_position: 4 title: "Epinio MCP Server Reference" -description: The Model Context Protocol server that exposes Epinio as tools for AI agents, and the capabilities it provides. +description: The Model Context Protocol server that exposes Epinio as tools for AI agents, and the optional elevated tier. keywords: [epinio, mcp, model context protocol, ai, agent, tools, claude] doc-type: [reference] doc-persona: [epinio-developer, epinio-operator] @@ -15,10 +15,15 @@ Epinio API as tools for AI agents such as Claude and other MCP-compatible client It translates MCP tool calls into Epinio REST API requests, so an agent can deploy and manage applications on your cluster through conversation. -:::caution Experimental -The MCP server is under active development and not yet stable. Tool names, -capabilities, and install steps may change. It is not recommended for production -use. +:::caution Beta +The MCP server is in beta. Tool names and options may still change, and it is +not yet recommended for production use. +::: + +:::info Requires Epinio 1.14.1 or later +The server depends on the builder-image, catalog-service, and app-chart CRUD API +and the source-retrieval endpoint, all introduced in Epinio 1.14.1. It will not +work against earlier releases. ::: To stand it up on your cluster, see [Install the MCP server](../getting-started/install-mcp). @@ -30,7 +35,7 @@ agent and the Epinio REST API to the cluster: ```text AI Agent (Claude, etc.) - | MCP protocol (Streamable HTTP, /mcp endpoint) + | MCP protocol (Streamable HTTP, served at the server root) Epinio MCP Server | REST API (Basic Auth or OIDC, TLS) Epinio API Server @@ -43,9 +48,13 @@ Authentication is per request: the agent passes an `Authorization` header Epinio. When no header is present, the server falls back to the credentials it was configured with (default `admin` / `password`). -## Tools +By default every tool wires **only** to the Epinio REST API, as the calling user. +An optional [elevated tier](#elevated-tier) that reaches directly into Kubernetes +is off unless explicitly enabled. -The server exposes 44 tools, grouped below by the area of Epinio they act on. +## Core tools + +These are always available and act purely through the Epinio API. ### Server and namespaces @@ -73,6 +82,9 @@ The server exposes 44 tools, grouped below by the area of Epinio they act on. | `app_logs` | Fetch runtime or staging/build logs from an application. | | `get_app_manifest` | Inspect full app configuration (image, routes, env, settings). | | `clone_app` | Clone an existing app to a new name using its built image. | +| `get_app_source` | Retrieve a deployed app's staging source (raw tarball or extracted files). | +| `list_app_files` | List file paths and sizes in a deployed app's source (no file contents). | +| `get_connection_info` | Return a ready-to-dial WebSocket URL for streaming an app's logs directly. | ### Environment variables @@ -92,62 +104,77 @@ The server exposes 44 tools, grouped below by the area of Epinio they act on. | `bind_configuration` | Bind configurations to an app. | | `unbind_configuration` | Unbind a configuration from an app. | -### Services +### Services and catalog | Tool | Description | | --- | --- | | `list_services` | List service instances in a namespace. | -| `list_catalog_services` | List available catalog services with their settings schemas. | -| `show_catalog_service` | Fetch a single catalog service's full details and settings schema. | -| `create_service` | Create a service from the catalog. | +| `create_service` | Create a service instance from a catalog entry. | | `delete_service` | Delete a service instance. | | `bind_service` | Bind a service to an app. | | `unbind_service` | Unbind a service from an app. | +| `list_catalog_services` | List catalog entries with their settings schemas. | +| `show_catalog_service` | Fetch a single catalog entry's details and settings schema. | +| `create_catalog_service` | Register a new catalog entry (service template). | +| `update_catalog_service` | Update a catalog entry. | +| `delete_catalog_service` | Delete a catalog entry. | -### Charts and builders +### App charts | Tool | Description | | --- | --- | -| `list_appcharts` | List AppCharts registered on the cluster (valid values for `appchart`), with per-chart settings schemas. | +| `list_appcharts` | List AppCharts registered on the cluster (valid values for `appchart`), with settings schemas. | | `show_appchart` | Fetch a single AppChart's description and settings schema. | -| `list_builders` | List Cloud Native Buildpacks builder images usable with this cluster and the ecosystems each supports. | -| `get_build_guidance` | Return guidance on deploying, appchart selection, builder selection, and build troubleshooting. | +| `create_appchart` | Register a new AppChart. | +| `update_appchart` | Update an AppChart. | +| `delete_appchart` | Delete an AppChart. | + +### Builder images + +The BuilderImage registry is the cluster's list of builder images an app can +stage with — the valid values for `push_app`'s `builder_image` parameter. + +| Tool | Description | +| --- | --- | +| `list_builder_images` | List registered builder images (the one marked default is used when none is given). | +| `show_builder_image` | Fetch a single builder image. | +| `create_builder_image` | Register a new builder image. | +| `update_builder_image` | Update a builder image. | +| `delete_builder_image` | Delete a builder image. | +| `get_build_guidance` | Guidance on deploying, appchart selection, builder selection, and build troubleshooting. | + +## Elevated tier + +A small set of capabilities reach **directly into Kubernetes** rather than +through the Epinio API — currently just workload **adoption**. They are **off by +default** and enabled with the `EPINIO_MCP_ELEVATED` environment variable, which +also requires the `standard-elevated` app chart's RBAC. See +[Install the MCP server](../getting-started/install-mcp) for how to turn it on. ### Adopting existing workloads | Tool | Description | | --- | --- | -| `adopt_app` | Bring an existing kubectl-managed Deployment into Epinio's view: label it, create an App CRD, and make it visible to `epinio app list/show/logs/exec`. | +| `adopt_app` | Bring an existing kubectl-managed Deployment into Epinio's view: label it, create an App CRD, and make it visible to `epinio app list/show/logs`. | | `reconcile_app` | Sync an adopted app's CRD to observed reality (image URL, routes from Ingresses). Supports `dry_run`. | | `release_app` | Remove Epinio labels and the App CRD for an adopted app. The underlying Deployment keeps running. | -### Capabilities and gated tools +When adoption is enabled, the core destructive tools (`delete_app`, +`restart_app`, `scale_app`, `update_app`, and configuration bind/unbind) refuse +to act on adopted apps — use `kubectl` for their lifecycle, or `release_app` to +convert back to a plain Kubernetes workload. + +### Capabilities | Tool | Description | | --- | --- | -| `check_capabilities` | Report readiness of optional capabilities (such as `app_editing`) and what is missing. | -| `enable_capability` | Fulfill a capability's satisfiable requirements (create service instances, bind configurations). | -| `get_app_source` | Retrieve a deployed app's staging tarball via the S3 gateway. Gated by the `app_editing` capability. | -| `list_app_files` | List file paths and sizes in a deployed app's source (no bytes returned). Gated by `app_editing`. | -| `get_connection_info` | Return the URL and forwarded OIDC token a caller needs to connect directly to a capability's backing service (for example, Epinio's log WebSocket). | - -## Optional capabilities (gated) - -Some tools require extra cluster infrastructure. They are gated behind named -capabilities so the server reports readiness explicitly instead of failing -silently. Call `check_capabilities` to see what is ready, and `enable_capability` -to fulfill the pieces it can. +| `check_capabilities` | Report readiness of optional capabilities and what is missing. | +| `enable_capability` | Fulfill a capability's satisfiable requirements. | -| Capability | Gates | Requires | +| Capability | Purpose | Requires | | --- | --- | --- | -| `app_editing` | `get_app_source`, `list_app_files` | An `s3-gateway` catalog entry and S3 credentials available to the server, plus `get apps.application.epinio.io` RBAC on the server's pod. | -| `log_streaming` | Advertises WebSocket reachability (environmental) | Ingress that preserves the `Upgrade` header and a reachable Epinio `/authtoken` endpoint. | -| `self_adoption` | Internal housekeeping (no gated tools) | The server's own App CRD exists, is annotated `epinio.io/adopted=true`, and matches the running Deployment. | - -`enable_capability` can fulfill the user-scope pieces (service instance, -configuration binding, self-adoption metadata, and writing S3 credentials into the -server's own Secret). Cluster-admin items, such as catalog install and -cross-namespace RBAC, are reported as `needs_admin`. +| `self_adoption` | Completes the MCP's own adoption when installed via `kubectl apply` | The server's own App CRD exists, is annotated `epinio.io/adopted=true`, and matches the running Deployment. | +| `log_streaming` | Reports WebSocket reachability for `get_connection_info` (diagnostic) | Ingress that preserves the `Upgrade` header and a reachable Epinio `/authtoken` endpoint. | ## Health probes diff --git a/docs/reference/principles.md b/docs/reference/principles.md index 359dcdbbc0f..9770654b641 100644 --- a/docs/reference/principles.md +++ b/docs/reference/principles.md @@ -1,5 +1,6 @@ --- sidebar_label: "Principles" +sidebar_position: 7 title: "Epinio design principles" description: The design principles Epinio is based upon. keywords: [epinio, kubernetes, design principles] diff --git a/docs/reference/security/_category_.json b/docs/reference/security/_category_.json index b821a3e992f..cd8dd76a638 100644 --- a/docs/reference/security/_category_.json +++ b/docs/reference/security/_category_.json @@ -1 +1 @@ -{ "label": "Security & auth", "position": 6, "collapsed": true } +{ "label": "Security & auth", "position": 10, "collapsed": true } diff --git a/docs/reference/security/authorization.md b/docs/reference/security/authorization.md index 58bb150c0dc..e1d8f4cb7c2 100644 --- a/docs/reference/security/authorization.md +++ b/docs/reference/security/authorization.md @@ -11,7 +11,7 @@ doc-topic: [epinio, reference, security, authorization] Since version **1.11.0** Epinio is shipped with a new authorization layer with two default roles: **admin** and **user**. Roles can be "namescoped", and they can be also customized with different permissions. -A user with the admin role will have the permission to perform any operation. A standard user will have only read permissions, but also has the permissions to create namespaces. When a user creates a namespace, they will automatically have the admin permission for it. +A user with the admin role will have the permission to perform any operation. A standard user has read access across resources and can create namespaces (automatically gaining admin permission on namespaces they create). As of 1.14.1 the default `user` role also grants builder-image management; see the role definition below. By default, after the installation two users are available: `admin` and `epinio`, both with the password `password`. The operator can control the creation of those users through the `api.users` key in [values.yaml](https://github.com/epinio/helm-charts/blob/main/chart/epinio/values.yaml). In a production setup, the default `api.users` value needs to be overridden. @@ -97,11 +97,14 @@ data: name: "Epinio User Role" default: "true" actions: | - namespace + namespace_write app_read configuration_read service_read gitconfig_read + export_registries_read + builderimage_read + builderimage_write ``` ### Fields @@ -129,7 +132,7 @@ These actions enable operations on Namespace commands and resources. ### App -These actions enable operations on App commands and resources. They also enable commands related to AppCharts (`epinio app chart`) and application environment variables. +These actions enable operations on App commands and resources, plus application environment variables. Read access to AppCharts comes bundled here (`app_read` depends on `chart_read`); AppChart *management* has its own actions, see [Chart](#chart) below. | Action ID | Description |-----------------------|------------- @@ -153,6 +156,26 @@ These actions enable operations on App commands and resources. They also enable | `app_portforward` | Open a tunnel with the `port-forward` command | `app` | All app permissions (including granular app actions, logs, exec and port-forward) +### Chart + +These actions enable operations on AppChart commands and resources (`epinio app chart`). AppCharts are cluster-scoped, so these actions are only effective when granted by a global (non-namespaced) role. + +| Action ID | Description +|----------------|------------- +| `chart_read` | Read permissions (list, show, match). Granted automatically to any role with `app_read`. +| `chart_write` | Write permissions (create, update, delete)
Depends on: `chart_read` +| `chart` | All the above
Depends on: `chart_read`, `chart_write` + +### Builder Image + +These actions enable operations on BuilderImage commands and resources. BuilderImages are cluster-scoped, so these actions are only effective when granted by a global (non-namespaced) role. + +| Action ID | Description +|----------------------|------------- +| `builderimage_read` | Read permissions (list, show, match) +| `builderimage_write` | Write permissions (create, update, delete)
Depends on: `builderimage_read` +| `builderimage` | All the above
Depends on: `builderimage_read`, `builderimage_write` + ### Configuration These actions enable operations on Configuration commands and resources. Be aware that to bind a configuration you still need the `app_write` permission as well. @@ -166,12 +189,12 @@ These actions enable operations on Configuration commands and resources. Be awar ### Service -These actions enable operations on Service commands and resources. +These actions enable operations on Service commands and resources, covering both service instances (namespaced) and catalog services (cluster-scoped). | Action ID | Description |-----------------------|------------- -| `service_read` | Read permissions (list, show) -| `service_write` | Write permissions (create, delete, bind, unbind)
Depends on: `service_read` +| `service_read` | Read permissions (list, show) for service instances and catalog services +| `service_write` | Write permissions for service instances (create, update, delete, bind, unbind) and catalog services (create, update, delete)
Depends on: `service_read` | `service_portforward` | Open a tunnel with the `port-forward` command | `service` | All the above
Depends on: `service_read`, `service_write`, `service_portforward` @@ -193,16 +216,25 @@ This action enable operations on Export Registries commands and resources. Only |---------------------------|------------- | `export_registries_read` | Read permissions +### Resource scope: cluster-scoped vs namespaced + +Epinio resources fall into two scopes, and the scope decides which of a user's roles can grant an action: + +- **Namespaced** resources (applications, configurations, service instances, and deleting an existing namespace) live inside a namespace. Actions on them are evaluated against the roles the user holds *for that namespace*, whether a namespace-scoped role such as `admin:workspace` or a global role. +- **Cluster-scoped** resources (app charts, builder images, git configs, catalog services, and creating a namespace) do not live in a namespace. Actions on them are evaluated against the user's **global** (non-namespaced) roles only. + +The practical consequence: a user who is admin of a single namespace (for example `admin:workspace`) can fully manage applications and delete that namespace, but cannot create an app chart, builder image, git config, catalog service, or a new namespace unless a global role grants it. The default `user` role is global, so everything it carries (including `namespace_write` and `builderimage_write`) applies cluster-wide. + ## Built-in Role Examples The following roles are shipped as ConfigMaps and can be assigned directly to users: | Role ID | Intended scope | |---------|----------------| -| `view_only` | Read-only access to application, configuration, service, gitconfig and export-registry resources | -| `application_developer` | Create/update applications without application delete and without non-application write permissions | -| `application_manager` | Full application CRUD and runtime operations, without non-application write permissions | -| `system_manager` | No-delete role: application create/update/runtime operations plus read-only access on other resource types | +| `view_only` | Read-only access across all resource types (applications, builder images, configurations, services, git configs, export registries) | +| `application_developer` | Application create/update (no delete) and runtime, plus builder-image, configuration and service write. No app-chart write | +| `application_manager` | Full application CRUD and runtime operations, plus builder-image, configuration and service write. No app-chart write | +| `system_manager` | No-delete role: application create/update/runtime, plus builder-image, app-chart, configuration and service write | ## Assign Roles to User diff --git a/docs/reference/upgrading.md b/docs/reference/upgrading.md index 9bc4784dd39..c4ba7f0281a 100644 --- a/docs/reference/upgrading.md +++ b/docs/reference/upgrading.md @@ -1,6 +1,6 @@ --- sidebar_label: Upgrading Epinio -sidebar_position: 8 +sidebar_position: 5 title: Upgrading Epinio description: Breaking changes and migration steps when upgrading Epinio between versions. keywords: [epinio, upgrade, migration, breaking changes, versions] @@ -13,6 +13,54 @@ Review the breaking changes and migration steps for your target version before upgrading. For the full list of releases and their release notes, see [versions](../versions.md). +## 1.13.X and 1.14.0 to 1.14.1 + +Git configuration handling changed. Selecting a configuration when deploying from a **private** +repository is now **explicit**: Epinio no longer implicitly matches a stored configuration to a +repository URL at push time. + +- **New private-repo pushes must select a git configuration.** In the dashboard, choose one in the + application's Git source. From the CLI or automation, the git origin must carry + `origin.git.gitconfig`; a push that sends no configuration clones unauthenticated and fails with + `authentication required`. +- **Existing applications keep working.** On redeploy, a compatibility fallback still matches + configuration-less apps to a stored configuration by repository URL, so they continue to clone as + before. +- **Credentials are bound to their instance host.** A configuration's credentials are only sent to + the host it is scoped to; selecting a configuration whose host does not match the repository is + rejected. +- **Global configurations are administrator-only to create.** Non-admin users can use global + configurations but cannot create them. + +This release also adds a new `BuilderImage` CRD and a `spec.origin.git.gitconfig` field on the +`apps` CRD. Helm never upgrades the contents of a chart's `crds/` directory on `helm upgrade`, so +the chart now runs a `pre-install`/`pre-upgrade` hook Job that applies the CRDs with `kubectl` and +waits for them to be established before the rest of the release. No manual `kubectl apply` is +required. See [Git Configuration](./concepts/git_configuration.md). + +The upgrade blocks on this hook and fails if the Job cannot run, so make sure it can. The Job pulls +the `kubectl` image (`image.kubectl.*`; mirror it first on air-gapped or private-registry clusters), +relies on the cluster-scoped RBAC the chart creates for it to manage `CustomResourceDefinitions`, +and runs with no custom `securityContext` (a `restricted` Pod Security label on the Epinio namespace +can reject it). If an upgrade hangs or rolls back, inspect the `epinio-crd-upgrade-` Job and +its logs in the Epinio namespace. If you instead manage CRDs out of band, apply the updated CRDs +yourself on upgrade so the new fields are not pruned. + +App Charts, Builder Images, and Catalog Services are now manageable through the API, which adds new +authorization actions. The shipped default `user` role and the built-in roles (`view_only`, +`application_developer`, `application_manager`, `system_manager`) already include `builderimage_read`, +so a default installation picks it up automatically on upgrade. + +If you use **custom roles**, add `builderimage_read` to them. It is required, not optional: it is not +implied by `app_read`, and the dashboard lists builder images both on the application create/deploy +screen and on the Builder Images page. Without it those views return `403 Forbidden`, so affected +users cannot deploy an application from the dashboard. Add the write actions only where users should +manage these resources: `builderimage_write` for Builder Images and `chart_write` to create, update, +or delete App Charts (`chart_read` is already implied by `app_read`). Creating, updating, or deleting +Catalog Services is now covered by the existing `service_write` right, so anyone granted +`service_write` can now manage the shared service catalog as well. See the +[authorization reference](./security/authorization.md#actions). + ## 1.13.X to 1.14.0 There are no breaking changes in this release. Documentation around performance was diff --git a/static/img/app-watch-1411.mp4 b/static/img/app-watch-1411.mp4 new file mode 100644 index 00000000000..ec48efc25aa Binary files /dev/null and b/static/img/app-watch-1411.mp4 differ