diff --git a/docs/contribute/development/server/_category_.json b/docs/contribute/development/server/_category_.json new file mode 100644 index 0000000000..17a3a12dbc --- /dev/null +++ b/docs/contribute/development/server/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Server", + "position": 4, + "collapsed": true +} diff --git a/docs/contribute/development/server/acceptance-tests.md b/docs/contribute/development/server/acceptance-tests.md new file mode 100644 index 0000000000..fa5b76f576 --- /dev/null +++ b/docs/contribute/development/server/acceptance-tests.md @@ -0,0 +1,90 @@ +--- +sidebar_label: 'Acceptance Tests' +sidebar_position: 1 +title: 'Acceptance Tests' +description: How to setup and run acceptance testing on the Epinio server. +keywords: [epinio, contributing, server, acceptance, testing] +doc-type: [contribute] +doc-topic: [server-contribution-acceptance-testing] +doc-persona: [epinio-developer] +--- + +# Acceptance Tests + +## Basic Run + +### Preparation + +An accessible Kubernetes instance is required to run the acceptance tests. +If none is available, K3d can be +[setup locally](../prereqs#starting-the-devcontainer). + +The Kubernetes instance needs to be prepared prior to the test run. K3d has +its own make target for the preparation which can be initiated by running +`make prepare_environment_k3d`. + +### Execution + +Invoke `make test-acceptance` to running the epinio acceptance tests +with its standard configuration. + +Invoke `make showfocus` to see if tests have been focused on. + +This target is automatically run as part of `make test-acceptance` as +well. + +## Configuration + +The tests can be configured by a mixture of environment variables, +files, and, of course, by editing the test go files. The latter to +focus a run on specific tests, as per ginkgo's documentation. + +### Environment variables + +#### Required + + 1. `KUBCONFIG`: This will give access the kubernetes cluster. + + 2. `EPINIO_SETTINGS`: This will provide credentials to be used by tests + to access the epinio server + + 3. `EPINIO_BINARY`: This will provide the path of epinio binary to be + used in the tests. + +#### Optional + + 1. `GINKGO_NODES`: The number of ginkgo nodes to distribute the + tests across. The default is `2`. The CI flows use `8`. + + 2. `FLAKE_ATTEMPTS`: The number of tries to perform when a test + fails, to ensure that the failure is real, and not a flake, + i.e. caused by a transient environmental condition. The default + is `2`. + +### Files + +All file paths are specified relative to the top level directory of +the epinio checkout running the acceptance tests. + + 1. `tmp/skip_cleanup`: If present system shutdown will not uninstall + epinio from the tests cluster, nor will it tear down the test + cluster. This allows future test runs to bypass the costly setup + of a cluster and epinio installation. + + This cannot be avoided if changes are made to the (un)install + code. This always requires a new epinio installation to test the + latest changes. + + On the third hand, changing the server code still allows using + this. In that case we simply cannot skip patching the server (See + `EPINIO_SKIP_PATCH`), as that step updates it to the local code, + and thus the last changes. + + 1. `tmp/after_each_sleep`: If present, readable, and containing an + integer number N the system will wait N seconds after each + test. Enables the developer to inspect the cluster's state after + a test. + + __Note__, the file has contain __only digits__, and nothing + else. Even a trailing newline after the digits prevents the + system from recognizing the request. \ No newline at end of file diff --git a/docs/contribute/development/ui/_category_.json b/docs/contribute/development/ui/_category_.json index 7cc426a3a4..30d03ec1d9 100644 --- a/docs/contribute/development/ui/_category_.json +++ b/docs/contribute/development/ui/_category_.json @@ -1,5 +1,5 @@ { "label": "UI", - "position": 4, + "position": 5, "collapsed": true } diff --git a/docs/contribute/helm-charts/_category_.json b/docs/contribute/helm-charts/_category_.json new file mode 100644 index 0000000000..259abdef16 --- /dev/null +++ b/docs/contribute/helm-charts/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Helm Charts", + "position": 4, + "collapsed": true +} diff --git a/docs/contribute/helm-charts/releasing-helm-charts.md b/docs/contribute/helm-charts/releasing-helm-charts.md new file mode 100644 index 0000000000..992df2c397 --- /dev/null +++ b/docs/contribute/helm-charts/releasing-helm-charts.md @@ -0,0 +1,63 @@ +--- +sidebar_label: Releasing Helm Charts +sidebar_position: 1 +title: Releasing Helm Charts +description: Overview of the process for publishing updated Epinio Helm charts. +keywords: [epinio, contribute, helm, charts, release] +doc-type: [contribute] +doc-topic: [epinio, contribute, helm, charts] +doc-persona: [epinio-developer, epinio-operator] +--- + +# Releasing Helm Charts + +The process for publishing updated Epinio Helm charts is automated and streamlined through GitHub Actions. + +## Overview + +There are two key GitHub Actions involved in the release workflow: + +- Build epiniod image +- Release Charts + +These actions work together to ensure charts are tested, packaged, and published automatically to the repository’s GitHub Pages branch. + +## Deployment Process + +### 1. Build epiniod image + +Once changes have been made to the Helm charts (for example, updating templates, values, or dependencies) and all tests are passing: + +- Navigate to the Actions tab in the repository. +- Run the “Build epiniod image” workflow. + +This action will: + +- Build and push the latest epiniod Docker image. +- Update the image reference used by the Helm charts. + +> Ensure that the chart changes are already committed and merged into the default branch before running this action. + +### 2. Release Charts + +After the image build completes successfully: + +- Run the “Release Charts” workflow. + +This action will: + +- Package the Helm charts. +- Create a new GitHub release with updated chart artifacts. +- Trigger the pages-build-deployment workflow. + +### 3. GitHub Pages Deployment + +The `pages-build-deployment` action automatically runs after the release. +It copies the packaged charts into the gh-pages branch, which serves as the Helm chart repository. + +Once this completes successfully, the updated Helm charts are available for installation via Helm: + +``` +helm repo add epinio https://epinio.github.io/helm-charts +helm repo update +``` \ No newline at end of file diff --git a/docs/reference/concepts/app-image-export.png b/docs/reference/concepts/app-image-export.png new file mode 100644 index 0000000000..8863ce7fcf Binary files /dev/null and b/docs/reference/concepts/app-image-export.png differ diff --git a/docs/reference/concepts/application-export.md b/docs/reference/concepts/application-export.md new file mode 100644 index 0000000000..a3c149bf34 --- /dev/null +++ b/docs/reference/concepts/application-export.md @@ -0,0 +1,24 @@ +--- +title: "Application Export" +sidebar_label: "Application Export" +description: "Reference material for how application exporting works in Epinio" +keywords: [epinio, application, app, export] +doc-type: [reference] +doc-persona: [epinio-developer, epinio-operator] +doc-topic: [epinio, reference, concepts, applications] +--- + +# Application Image Export + +The `epinio app export` command provides the ability to retrieve all parts of an application (the helm chart, its values and the container image) and save them in the local filesystem. + +The [`skopeo`](https://github.com/containers/skopeo) cli is used to download the image from the registry. This was chosen over the standard `docker` cli because it doesn't need a demon to run, nor does it require root for most of its operations, and it is OCI compliant. + +When a client requests the export of the image of an application from the Epinio server, the server first executes a Kubernetes job. This job runs the `skopeo copy` command that fetches the image from the registry. The image is stored on the PVC shared with the Epinio server. Once downloaded the image is served to the client that requested it. + +Cleanup is done only if all the operations succeeded. The job will be not removed if some error occurs, to keep the logs for further investigations. + +Application Export Flow