diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml new file mode 100644 index 0000000..e71cc4e --- /dev/null +++ b/.github/workflows/deploy-gh-pages.yaml @@ -0,0 +1,41 @@ +name: Deploy GH Pages +on: + push: + branches: + - main + - feature/developer-hub + paths: + - 'mkdocs.yml' + - 'docs/**' + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: 3.x + + - name: Set cache id + run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + + - name: Use cache + uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + + - name: Install mkdocs-material and plugins + run: pip install mkdocs-material + + - name: Deploy to GH Pages + run: mkdocs gh-deploy --force diff --git a/Taskfile.yaml b/Taskfile.yaml new file mode 100644 index 0000000..29c4ed7 --- /dev/null +++ b/Taskfile.yaml @@ -0,0 +1,7 @@ +version: 3 + +tasks: + serve: + desc: Run local dev server + cmds: + - docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material diff --git a/docs/Guidelines/PDG_0_-_Changelog & Drafts/index.md b/docs/Guidelines/PDG_0_-_Changelog & Drafts/index.md new file mode 100644 index 0000000..b0faebf --- /dev/null +++ b/docs/Guidelines/PDG_0_-_Changelog & Drafts/index.md @@ -0,0 +1,5 @@ +# Changelog of Pmoscode Developer Guidelines (PDGs) + +| Created | Post-History | +|-------------|----------------------------------------------------------------------------------------------| +| 01-Sep-2023 | Initial contribution | diff --git a/docs/Guidelines/PDG_0_-_Changelog & Drafts/trg-0-template.md b/docs/Guidelines/PDG_0_-_Changelog & Drafts/trg-0-template.md new file mode 100644 index 0000000..5fefb71 --- /dev/null +++ b/docs/Guidelines/PDG_0_-_Changelog & Drafts/trg-0-template.md @@ -0,0 +1,18 @@ +# PDG 0.1 - Templates + +This is the template for new PDG's. + +| Status | Created | Post-History | +|------------|--------------|--------------------------------------------| +| Deprecated | 05-May-2023 | Deprecated it because obsolete or outdated | +| Active | 27-Feb-2023 | Mark active without limitations | +| Draft | 13-Sept-2022 | Initial contribution | + +## Why + +Here you will find the purpose of this PDG. For example, because it makes it much easier for others to use, or it's a default style convention, ... + +## Description + +Here you will find the description of the PDG. +Provides best practices: In the best case with code example or/and step-by-step guide. diff --git a/docs/Guidelines/PDG_1_-_Documentation/pdg-1-1.md b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-1.md new file mode 100644 index 0000000..9b0cfad --- /dev/null +++ b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-1.md @@ -0,0 +1,21 @@ +# PDG 1.1 - README.md + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 01-Sep-2023 | | + +## Why + +A good written `README.md` file is the entry point for everyone visiting a repository. It should contain all necessary information. + +## Description + +Each repository **must** contain a `README.md` file which **shall** cover the following topics: + +- A short introduction to the software component it offers +- Basic description of the repository and its content +- Installation instructions to get component working +- If required, additional post-installation configuration steps to finish installation +- Optional: Development / contribution instructions + +If installation instructions are too comprehensive for the `README.md`, move content to `INSTALL.md` file and reference it here. See [PDG 1.2](pdg-1-2.md). diff --git a/docs/Guidelines/PDG_1_-_Documentation/pdg-1-2.md b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-2.md new file mode 100644 index 0000000..8ed1754 --- /dev/null +++ b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-2.md @@ -0,0 +1,15 @@ +# PDG 1.2 - INSTALL.md + +| Status | Created | Post-History | +|--------|--------------|--------------| +| Active | 01-Sep-2023 | | + +## Why + +When a repository contains code which needs to be configured/setup or installed, the `README.md` file should cover this information. +If this is too much content, it can be moved into a `INSTALL.md` file and referenced in the README.md. + +## Description + +Create a `INSTALL.md` file in the main folder of the repository and add all installation relevant information. +Also add all post-installation configuration steps to finish installation. diff --git a/docs/Guidelines/PDG_1_-_Documentation/pdg-1-3.md b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-3.md new file mode 100644 index 0000000..ddf3c4e --- /dev/null +++ b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-3.md @@ -0,0 +1,19 @@ +# PDG 1.3 - CHANGELOG.md + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 01-Sep-2023 | | + +## Why + +Knowing of what changes have been made is very important. Getting information about features, bug and security fixes are mandatory. + +This helps everyone who is using the software to understand what version to choose or when to upgrade. + +## Description + +To track changes of releases a `CHANGELOG.md` **must** exist in repositories. The format **should** follow the [Keep A Changelog](https://keepachangelog.com/en/1.0.0/). + +The versioning of releases **must** follow [semantic versioning](https://semver.org/). + +For easy changelog creation, [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) **should** be applied to every commit. diff --git a/docs/Guidelines/PDG_2_-_GIT/pdg-2-1.md b/docs/Guidelines/PDG_2_-_GIT/pdg-2-1.md new file mode 100755 index 0000000..c249382 --- /dev/null +++ b/docs/Guidelines/PDG_2_-_GIT/pdg-2-1.md @@ -0,0 +1,13 @@ +# PDG 2.1 - Default Branch + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 22-Dec-2023 | | + +## Why + +This is a personal decision. But future features or requirements could demand on it. E.g.: for security scanning. + +## Description + +Default branch **must** be `main`. diff --git a/docs/Guidelines/PDG_2_-_GIT/pdg-2-2.md b/docs/Guidelines/PDG_2_-_GIT/pdg-2-2.md new file mode 100755 index 0000000..5c9caf8 --- /dev/null +++ b/docs/Guidelines/PDG_2_-_GIT/pdg-2-2.md @@ -0,0 +1,49 @@ +# PDG 2.3 - Repo structure + + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 22-Dec-2023 | | + +## Why + +To have a unified and common repository structure is helpful when working in more than one project. It can be adapted but should remain consistent. + +## Description + +All repositories **must** contain the following files and folders: + +```text +CONTRIBUTING.md +LICENSE +README.md +CODE_OF_CONDUCT.md +``` + +**Optional** files and folders: + +```text +AUTHORS.md +INSTALL.md +SECURITY.md +``` + +### Files + +#### README.md + +Your repository **must** contain a `README.md` file. See [PDG 1.1 - README.md](../PDG_1_-_Documentation/PDG-1-1). + +#### INSTALL.md + +Your repository **should** contain a `INSTALL.md` file. See[PDG 1.2 - INSTALL.md](../PDG_1_-_Documentation/PDG-1-2). + +#### Legal documentation + +For the following files, see [PDG 7.01](../PDG_7_-_Open_Source_Governance/PDG-7-1) + +- AUTHORS.md (optional) +- CODE_OF_CONDUCT.md +- CONTRIBUTING.md +- LICENSE +- SECURITY.md diff --git a/docs/Guidelines/PDG_3_-_Kubernetes/trg-3-1.md b/docs/Guidelines/PDG_3_-_Kubernetes/trg-3-1.md new file mode 100755 index 0000000..532c463 --- /dev/null +++ b/docs/Guidelines/PDG_3_-_Kubernetes/trg-3-1.md @@ -0,0 +1,49 @@ +--- +title: PDG 3.01 Superseded Supported Versions +--- + +| Status | Created | Post-History | +|------------|--------------|----------------------| +| Superseded | 08-Mar-2023 | Marked as superseded | +| Moved | 02-Jan-2023 | content moved | +| Draft | 13-Sept-2022 | n/a | + +## Superseded by PDG 5.09 - Helm test + +This is superseded by [PDG 5.09 - Helm test](../PDG%205%20-%20Helm/PDG-5-09) + +## ~~Description~~ + +~~As new Kubernetes versions are released every few months, teams need to support 3 versions at a time:~~ + +- latest +- latest - 1 +- latest - 2 + +~~For checking the current versions available please use the [AKS Kubernetes release calendar](https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar). The __AKS GA__ column is relevant and determines which is the Azure release date of a Kubernetes version. Example: at 02-Jan-2023 the current AKS GA version is 1.25, therefore the supported versions are 1.25, 1.24 and 1.23.~~ + +## ~~Testing compatibility~~ + +~~For testing whether the application is compatible with the supported Kubernetes versions CI/CD pipeline integration or local deployment is recommended. For local deployment please see [Kind](https://kind.sigs.k8s.io/) clusters where a Kubernetes cluster can be started with a [specific version](https://kind.sigs.k8s.io/docs/user/configuration/#kubernetes-version) locally on a development machine. Example for example:~~ + +```yaml +# config.yaml +kind: Cluster +apiVersion: kind.x-k8s.io/v1alpha4 +nodes: +- role: control-plane +- role: worker + image: kindest/node:v1.25.3@sha256:f1de3b0670462f43280114eccceab8bf1b9576d2afe0582f8f74529da6fd0365 +``` + +~~After Kind is installed locally, run the following command with the config above:~~ + +```sh +kind create cluster --config=config.yaml +``` + +~~A Kubernetes node will start with version 1.25.~~ + +## ~~Why~~ + +~~New Kubernetes minor versions are released quite frequently with bugfixes, security patches and new features. Clusters implement these new versions at a different pace but the applications that are deployed there has to be supported.~~ diff --git a/docs/Guidelines/PDG_3_-_Kubernetes/trg-3-2.md b/docs/Guidelines/PDG_3_-_Kubernetes/trg-3-2.md new file mode 100755 index 0000000..acc7ed7 --- /dev/null +++ b/docs/Guidelines/PDG_3_-_Kubernetes/trg-3-2.md @@ -0,0 +1,54 @@ +--- +title: PDG 3.02 - Persist Data +--- + +| Status | Created | Post-History | +|--------|-------------|-----------------| +| Draft | 17-Jul-2023 | 'loos' typo fix | +| Active | 07-Mar-2023 | | +| Draft | 02-Jan-2023 | n/a | +| Moved | 02-Jan-2023 | content moved | + +## Why + +In cases where data has to be persisted (database, uploaded files etc.), Kubernetes **must** be configured to create Persistent Volume that is attached to an storage created by a storage provider, where data remains even after the deletion of the application. Otherwise, an incidental deletion will delete all state. + +## Description + +Using stateful data requires additional caution to not lose data by accident. Therefore, when a pod/deployment/statefulset resource is removed, data will still be available on the StorageClass's disk that was used. + +## How + +Example PersistentVolumeClaim: + +```yaml +# pvc.yaml +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: pvc-persistent-tmp-demo +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 50Mi +``` + +This can be referenced in the volumes section of a Pod/Deployment/StatefulSet resource: + +```yaml +# deployment.yaml +#... + volumes: + - name: pv-tmp-demo + persistentVolumeClaim: + claimName: pvc-persistent-tmp-demo +#... +``` + +:::tip + +It is not recommended to directly request the claim in a StatefulSet! Rather create the PVC separately and reference that as an existing claim. See the example in [Bitnami's Postgresql chart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql) where an existing claim can be referenced for the primary database at the [primary.persistence.existingClaim property](https://github.com/bitnami/charts/tree/main/bitnami/postgresql#postgresql-primary-parameters). + +::: diff --git a/docs/Guidelines/PDG_4_-_Container/assets/trg4-1-semver-image.png b/docs/Guidelines/PDG_4_-_Container/assets/trg4-1-semver-image.png new file mode 100755 index 0000000..8f54c48 Binary files /dev/null and b/docs/Guidelines/PDG_4_-_Container/assets/trg4-1-semver-image.png differ diff --git a/docs/Guidelines/PDG_4_-_Container/pdg-4-1.md b/docs/Guidelines/PDG_4_-_Container/pdg-4-1.md new file mode 100755 index 0000000..74f16ca --- /dev/null +++ b/docs/Guidelines/PDG_4_-_Container/pdg-4-1.md @@ -0,0 +1,133 @@ +# PDG 4.01 - Image tagging + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 22-Dec-2023 | | + +## Why + +Using non-specific image tags like `:latest` would require everyone to find and check long hashes instead of a version number. + +This also breaks control of selecting specific versions and upgrading as `:latest` would pull in new images on restart of a pod. + +Container image tagging also helps you to match [PDG 5.05 - Chart Values](../PDG_5_-_Helm/PDG-5-5.md#container-images). + +## Description + +The build process for container images **must** ensure proper image tagging. All images **must** be tagged +following [semantic versioning](https://semver.org/), e.g. `:0.1.2` as well as the latest image must be tagged in +addition with `:latest`. + +### Process example description + +If you follow our recommendation how to create container images and tag them, the following list describes the process +steps: + +1\. Create/edit your `Dockerfile` and merge Changes via PullRequest to `main` branch, if changes where made in a feature + branch, or similar. + +2\. Create/push a Git tag to `main` branch, e.g.: + + ```shell + > git pull + remote: Enumerating objects: 129, done. + remote: Counting objects: 100% (84/84), done. + remote: Compressing objects: 100% (65/65), done. + remote: Total 129 (delta 29), reused 11 (delta 10), pack-reused 45 + ... + > git tag -a v1.2.3 -m "annotation text goes here" + > git push origin v1.2.3 + ``` + +!!! warning "Caution" + Git CLI will create tag on the latest (local) commit. Ensure to be up-to-date with the remote after, + otherwise [use commit ID](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_tagging_later) while creating the + tag. + +!!! tip "Tip" + Prefer annotated tags over lightweight tags. Refer to [Git documentation](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_creating_tags) about tags. + +3\. Pushing the tag will trigger the GH workflow to build your Docker image + +4\. After the finishing the build workflow, your repository will contain proper versioned Docker images, e.g.: + + ![SemVer Docker images](assets/PDG4-1-semver-image.png) + +### Implementation + +Create a GitHub Workflow file with following content: + +```yaml +name: Build - Docker image (SemVer) + +on: + push: + branches: + - main + # trigger events for SemVer like tags + tags: + - 'v*.*.*' + - 'v*.*.*-*' + pull_request: + branches: + - main + +env: + IMAGE_NAMESPACE: "tractusx" + IMAGE_NAME: "YourApplicationName" + +jobs: + docker: + runs-on: ubuntu-latest + permissions: + packages: write + + steps: + - name: Checkout + uses: actions/checkout@v3 + + # Create SemVer or ref tags dependent of trigger event + - name: Docker meta + id: meta + uses: docker/metadata-action@v4 + with: + images: | + ${{ env.IMAGE_NAMESPACE }}/${{ env.IMAGE_NAME }} + # Automatically prepare image tags; See action docs for more examples. + # semver patter will generate tags like these for example :1 :1.2 :1.2.3 + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}} + type=semver,pattern={{major}}.{{minor}} + + - name: DockerHub login + if: github.event_name != 'pull_request' + uses: docker/login-action@v2 + with: + # Use existing DockerHub credentials present as secrets + username: ${{ secrets.DOCKER_HUB_USER }} + password: ${{ secrets.DOCKER_HUB_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v3 + with: + context: . + # Build image for verification purposes on every trigger event. Only push if event is not a PR + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + + # https://github.com/peter-evans/dockerhub-description + # Important step to push image description to DockerHub + - name: Update Docker Hub description + if: github.event_name != 'pull_request' + uses: peter-evans/dockerhub-description@v3 + with: + # readme-filepath defaults to toplevel README.md, Only necessary if you have a dedicated file with your 'Notice for docker images' + # readme-filepath: path/to/dedicated/notice-for-docker-image.md + username: ${{ secrets.DOCKER_HUB_USER }} + password: ${{ secrets.DOCKER_HUB_TOKEN }} + repository: ${{ env.IMAGE_NAMESPACE }}/${{ env.IMAGE_NAME }} +``` diff --git a/docs/Guidelines/PDG_4_-_Container/pdg-4-2.md b/docs/Guidelines/PDG_4_-_Container/pdg-4-2.md new file mode 100755 index 0000000..a2f1553 --- /dev/null +++ b/docs/Guidelines/PDG_4_-_Container/pdg-4-2.md @@ -0,0 +1,51 @@ +--- +title: PDG 4.03 - Non-root container +--- + +| Status | Created | Post-History | +|--------|--------------|----------------------------------| +| Active | 29-Dec-2022 | Initial Release | +| Draft | 14-Sept-2022 | Draft | + +## Why + +Normally containers do not need root permission but if a container image runs as root, a compromised container has potentially root permissions on the underlying node. + +For security reasons this is **must** be followed. + +## Description + +### Implementation + +The container's **Dockerfile** and the **Pod resource file (yaml)** has to be modified to be able to run as a non-root user. + +- Modify the image's Dockerfile with a `RUN` command that adds a non-root user and a `USER` command that specifies which user runs the container on startup. The example below can be modified for specific needs/requirements. + +```Dockerfile +#Pull the base image as Ubuntu +FROM ubuntu:latest + +#Add a user with userid 8877 and name nonroot +RUN useradd −u 8877 nonroot + +#Run Container as nonroot +USER nonroot +``` + +- Modify the [Pod's or Deployment's configuration](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container) by adding `runAsUser` field for both the pod's and container's securityContext section. Also set the `allowPrivilegeEscalation` to `false` on the container's securityContext. See the example below: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: example-pod +spec: + securityContext: + runAsUser: 1000 # SPECIFY USER ID HERE + containers: + - name: example-container + image: gcr.io/google-samples/node-hello:1.0 + securityContext: + runAsUser: 1000 # SPECIFY USER ID HERE + allowPrivilegeEscalation: false # SET THIS TO FALSE +``` diff --git a/docs/Guidelines/PDG_4_-_Container/pdg-4-3.md b/docs/Guidelines/PDG_4_-_Container/pdg-4-3.md new file mode 100755 index 0000000..5aca65c --- /dev/null +++ b/docs/Guidelines/PDG_4_-_Container/pdg-4-3.md @@ -0,0 +1,18 @@ +--- +title: PDG 4.04 - Image signing +--- + +| Status | Created | Post-History | +|--------|--------------|-----------------| +| Active | 04-Jan-2023 | Initial release | +| Draft | 13-Sept-2022 | n/a | + +## Why + +We need to make sure that we only use the images that can be trusted, therefore all images **must** be signed by an official entity. + +## Description + +Image signing is a process where the publisher use the digital signatures when pushing images into repository, and it allows verification from image consumers. The publisher can manually sign the image or have the signing process a part of their software release process. Check [here](https://docs.docker.com/engine/security/trust/#signing-images-with-docker-content-trust) to learn how it works. + +At the moment the **image signing** is **not supported** yet but please do expect an update here. diff --git a/docs/Guidelines/PDG_4_-_Container/pdg-4-4.md b/docs/Guidelines/PDG_4_-_Container/pdg-4-4.md new file mode 100755 index 0000000..fd371b4 --- /dev/null +++ b/docs/Guidelines/PDG_4_-_Container/pdg-4-4.md @@ -0,0 +1,108 @@ +--- +title: PDG 4.05 - Container registries +--- + +:::caution +Proposed release date: "mandatory after": 19th of May 2023 +::: + +| Status | Created | Post-History | +|--------|--------------|-------------------------------------------------------------------------| +| Draft | 04-May-2023 | Place DockerHub as mandatory container registry; remove GHCR references | +| Active | 05-Jan-2023 | Initial release | +| Draft | 14-Sept-2022 | n/a | + +## Why + +Using a central container registry greatly improves security and manageability of images. It also makes it easier for external parties to validate that images are correct if they are coming from the same source. + +## Description + +In Eclipse Tractus-X we are using one central container registry. This registry ist [tractusx on DockerHub](https://hub.docker.com/u/tractusx). + +All container images released for an Eclipse Tractus-X product **must** be present on [DockerHub](https://hub.docker.com/u/tractusx). +Also be aware of the necessary remarks for container images described in [PDG 4-06](./PDG-4-06.md) and alignment on common base images +described in [PDG 4.02](./PDG-4-02.md). + +## How + +Following example shows a simple workflow, that can be used to publish your Docker image(s) to `DockerHub`. +It is using secrets, that contain credentials to authenticate at `DockerHub`. These secrets are present at GitHub organization +level and can therefore be used in any repository in our org. + +```yaml +# Reference from https://github.com/eclipse-tractusx/app-dashboard/blob/main/.github/workflows/build-image.yaml +# You might want to check the source for recent updates +name: Build - Docker image (SemVer) + +on: + push: + branches: + - main + # trigger events for SemVer like tags + tags: + - 'v*.*.*' + - 'v*.*.*-*' + pull_request: + branches: + - main + +env: + IMAGE_NAMESPACE: "tractusx" + IMAGE_NAME: "app-dashboard" + +jobs: + docker: + runs-on: ubuntu-latest + permissions: + packages: write + + steps: + - name: Checkout + uses: actions/checkout@v3 + + # Create SemVer or ref tags dependent of trigger event + - name: Docker meta + id: meta + uses: docker/metadata-action@v4 + with: + images: | + ${{ env.IMAGE_NAMESPACE }}/${{ env.IMAGE_NAME }} + # Automatically prepare image tags; See action docs for more examples. + # semver patter will generate tags like these for example :1 :1.2 :1.2.3 + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}} + type=semver,pattern={{major}}.{{minor}} + + - name: DockerHub login + if: github.event_name != 'pull_request' + uses: docker/login-action@v2 + with: + # Use existing DockerHub credentials present as secrets + username: ${{ secrets.DOCKER_HUB_USER }} + password: ${{ secrets.DOCKER_HUB_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v3 + with: + context: . + # Build image for verification purposes on every trigger event. Only push if event is not a PR + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + + # https://github.com/peter-evans/dockerhub-description + # Important step to push image description to DockerHub + - name: Update Docker Hub description + if: github.event_name != 'pull_request' + uses: peter-evans/dockerhub-description@v3 + with: + # readme-filepath defaults to toplevel README.md, Only necessary if you have a dedicated file with your 'Notice for docker images' + # readme-filepath: path/to/dedicated/notice-for-docker-image.md + username: ${{ secrets.DOCKER_HUB_USER }} + password: ${{ secrets.DOCKER_HUB_TOKEN }} + repository: ${{ env.IMAGE_NAMESPACE }}/${{ env.IMAGE_NAME }} +``` diff --git a/docs/Guidelines/PDG_4_-_Container/pdg-4-5.md b/docs/Guidelines/PDG_4_-_Container/pdg-4-5.md new file mode 100755 index 0000000..fe88660 --- /dev/null +++ b/docs/Guidelines/PDG_4_-_Container/pdg-4-5.md @@ -0,0 +1,131 @@ +--- +title: PDG 4.06 - Notice for docker images +--- + +:::caution +Proposed release date: "mandatory after": 19th of May 2023 +::: + +| Status | Created | Post-History | +|--------|-------------|------------------| +| Draft | 04-May-2023 | Initial release | + +## Why + +Due to legal constrains we need to annotate the released container images to make it clear that we do our best to provide good images for demo purposes, +but we do not provide any legal guarantee. +This has to be defined in a dedicated 'Notice for docker image' section in our repositories and on the respective image page on `DockerHub`. + +## Description + +There are a few properties and links, that **must** be present on each notice, but they do vary for each image and product. +The minimum set of information is: + +- Link to the source of your base image (Container registry and GitHub if available) +- Link to your product image on `DockerHub` +- Link to your repository on GitHub +- Direct link to the Dockerfile used to build your image +- Link to `LICENCE` file in your repo as 'Project License' (make clear, that this is the PROJECT licence, not an image license) + +## How and where to annotate the base image + +The above information **must** be provided in Markdown format, either in your toplevel `README.md`, or in a dedicated +notice Markdown file, that you then reference from your toplevel `README.md`. + +A dedicated notice file can be necessary, if you built multiple container image from a single repository. +Multiple notice files ensure, that you can directly link the specific `Dockerfile`, that is used and include it in the description, that is pushed to `DockerHub`. + +The notice **must** always start with the following headline and the reference to your image on `DockerHub` +(example taken from [app-dashboard](https://github.com/eclipse-tractusx/app-dashboard#notice-for-docker-image): + +```markdown +## Notice for Docker image + +DockerHub: [https://hub.docker.com/r/tractusx/app-dashboard](https://hub.docker.com/r/tractusx/app-dashboard) +``` + +Following this, you **must** provide additional information on your product: +(example taken from [app-dashboard](https://github.com/eclipse-tractusx/app-dashboard#notice-for-docker-image): + +```markdown +Eclipse Tractus-X product(s) installed within the image: + +____ + +- GitHub: https://github.com/eclipse-tractusx/ +- Project home: https://projects.eclipse.org/projects/automotive.tractusx +- Dockerfile: https://github.com/eclipse-tractusx//blob/main/ +- Project license: [Apache License, Version 2.0](https://github.com/eclipse-tractusx//blob/main/LICENSE) +``` + +The last bits of information you **must** provide is related to your used base image. +As previously described, the following information should be provided, if available: + +- DockerHub links +- GitHub repo +- direct links to Dockerfile + +The following example is taken from the [IRS product](https://github.com/eclipse-tractusx/item-relationship-service#notice-for-docker-image): + +```markdown +**Used base image** + +- [eclipse-temurin:20-jre-alpine](https://github.com/adoptium/containers) +- Official Eclipse Temurin DockerHub page: https://hub.docker.com/_/eclipse-temurin +- Eclipse Temurin Project: https://projects.eclipse.org/projects/adoptium.temurin +- Additional information about the Eclipse Temurin images: https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin +``` + +Closing the notice, we provide a general statement about potentially contained other tools and the demo/experimental purpose +of our images. We use the following text: + +```markdown +As with all Docker images, these likely also contain other software which may be under other licenses +(such as Bash, etc. from the base distribution, along with any direct or indirect dependencies of the primary software being contained). + +As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. +``` + +## Examples + +The following examples are shown as reference, to see already existing and complete versions of a 'Notice for docker images'. +They **can not** be used for your product without modifications. + +Good example for notice integrated in toplevel `README.md`: [IRS](https://github.com/eclipse-tractusx/item-relationship-service#notice-for-docker-image) + +Good example for a dedicated notice file: [edc-controlplane-memory-hashicorp-vault](https://github.com/eclipse-tractusx/tractusx-edc/edit/main/edc-controlplane/edc-controlplane-memory-hashicorp-vault/notice.md) + +## Already collected base image information + +The following sections contain information, that already has been collected on base images, that are used in Eclipse Tractus-X. +You can use that information for your own notice. **Be careful**, when it comes to version, like JRE versions for example. +You have to adapt some of the provided links to match your used version. + +### Eclipse Temurin (JRE) + +- Base image reference (example) `eclipse-temurin:20-jre-alpine` +- [GitHub repo](https://github.com/adoptium/containers) +- [Official Eclipse Temurin DockerHub page](https://hub.docker.com/_/eclipse-temurin) +- [Eclipse Temurin Project](https://projects.eclipse.org/projects/adoptium.temurin) +- [Additional information about the Eclipse Temurin images](https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin) + +### Nginx-unprivileged (serve static HTML and JS bundles) + +- Base image reference (example) `nginxinc/nginx-unprivileged:alpine` +- [Dockerfile (alpine)](https://github.com/nginxinc/docker-nginx-unprivileged/blob/main/Dockerfile-alpine.template) +- GitHub project: [https://github.com/nginxinc/docker-nginx-unprivileged](https://github.com/nginxinc/docker-nginx-unprivileged) +- DockerHub: [https://hub.docker.com/r/nginxinc/nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) + +### .NET runtime + +- Base image reference (example): `mcr.microsoft.com/dotnet/runtime:6.0-alpine` +- Dockerfile (:6-alpine): [mcr.microsoft.com/dotnet/runtime:6.0-alpine](https://github.com/dotnet/dotnet-docker/blob/e1984aaea51a796b68f6672749d280525c30e063/src/runtime/6.0/alpine3.17/amd64/Dockerfile) +- GitHub project: [https://github.com/dotnet/dotnet-docker](https://github.com/dotnet/dotnet-docker) +- DockerHub: [https://hub.docker.com/_/microsoft-dotnet-runtime](https://hub.docker.com/_/microsoft-dotnet-runtime) + +### ASP.NET core runtime + +- Base image reference (example): `mcr.microsoft.com/dotnet/aspnet:6.0-alpine` +- Dockerfile (:6-alpine): [mcr.microsoft.com/dotnet/aspnet:6.0-alpine](https://github.com/dotnet/dotnet-docker/blob/e1984aaea51a796b68f6672749d280525c30e063/src/aspnet/6.0/alpine3.17/amd64/Dockerfile) +- GitHub project: [https://github.com/dotnet/dotnet-docker](https://github.com/dotnet/dotnet-docker) +- DockerHub: [https://hub.docker.com/_/microsoft-dotnet-aspnet](https://hub.docker.com/_/microsoft-dotnet-aspnet) diff --git a/docs/Guidelines/PDG_5_-_Helm/pdg-5-5.md b/docs/Guidelines/PDG_5_-_Helm/pdg-5-5.md new file mode 100755 index 0000000..a289c19 --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/pdg-5-5.md @@ -0,0 +1,49 @@ +--- +title: PDG 5.05 - Chart Values +--- + +| Status | Created | Post-History | +|--------|--------------|-----------------| +| Active | 10-Nov-2022 | Initial release | + +## Why + +When external entities need to setup a whole Eclipse Tractus-X setup, they might need to configure multiply helm charts. To reduce errors and make it efficient overall, this guide aligns basic helm values across all products. + +## Description + +Best practices for Helm chart `values.yaml` file. + +## Container images + +A proper section for Container images **should** look like this: + +```yaml +image: + registry: docker.io + repository: bitnami/postgresql + tag: 14.5.0-debian-11-r19 + digest: "" + ## Specify an imagePullPolicy + ## Defaults to 'Always' if image tag is 'latest', else set to 'IfNotPresent' + ## ref: https://kubernetes.io/docs/user-guide/images/#pre-pulling-images + ## + pullPolicy: IfNotPresent + ## Optionally specify an array of imagePullSecrets. + ## Secrets must be manually created in the namespace. + ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ + ## Example: + ## pullSecrets: + ## - myRegistryKeySecretName + ## + pullSecrets: [ ] + ## Set to true if you would like to see extra information on logs + ## +``` + +:::caution do not use `latest` as image tag! + +This might cause unexpected effects, as the Helm release could change without bumping the chart version! Also due to +security reasons you shall not use `latest` tag. + +::: diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-01.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-01.md new file mode 100755 index 0000000..9867411 --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-01.md @@ -0,0 +1,60 @@ +--- +title: PDG 5.01 - Helm Chart requirements +--- + + | Status | Created | Post-History | +|--------|-------------|-----------------| +| Active | 10-Nov-2022 | Initial release | + +## Why + +Eclipse Tractus-X consists of many independent and dependent components and products. While previously software was installed through installers like `setup.exe` or linux packages, in the cloud native world with kubernetes, the alignment options on how to setup is limited. + +One versatile and well known industry standard are **helm charts**. + +## Description + +All Eclipse Tractus-X components **must** be installable via Helm and meet following requirements. The product's Helm +chart **has to meet** all of these criteria! + +- Helm chart **must be released**. +- Appropriate versioning for `version` and `appVersion` has to be used in `Chart.yaml` +- The released Helm chart **must not** contain any environment specific `values-xyz.yaml` files +- Helm chart `values.yaml` file **must** contain proper default values/placeholders + - No hostname provided for ingress + - Ingress is disabled + - No references to any secret engine service (e.g.: Hashicorp Vault) + - Dependencies should be prefixed with the `nameOverride` and/or `fullnameOverride` properties + - Image tag is set to the **Chart.yaml** `appVersion` property +- Helm chart **must be deployable to any environment without overwriting default values** with a simple `helm install` + command +- If there is an **Ingress** resource present, it can be turned off, and it is disabled by default +- Helm dependencies have to be declared in `Chart.yaml` file + +### Released Helm Charts + +Eclipse Tractus-X components can only be used and bundled with other components of Tractus-X if there is a version of the +component with reliable content. This can only be achieved by creating a release of your Helm chart. + +We recommend to use GitHub [Chart Releaser Action](https://github.com/helm/chart-releaser-action). + +### Versioning + +Versioning is essential when it comes to releasing Helm charts. In an ideal world your chart version (defined +in `version` inside `Chart.yaml`) matches the application version (defined in `appVersion` inside `Chart.yaml`) which +the Helm chart will deploy. This makes it for users easier to get an idea what will be installed in which version. +Please refer also to [PDG 5.03 - Version strategy](PDG-5-03.md). + +To achieve a proper versioning of your Helm chart keep in mind, that it **shall not** contain version information that could +change outside the Helm chart, e.g. container image tags (-> don't use container image tag *latest*). + +### The `values.yaml` File + +The `values.yaml` file is essential for Helm charts. The file **must** contain all values the chart is expecting and +there **must** be no other values files except of `values.yaml` file. Released Helm charts **must** contain +only `values.yaml` file. + +### Dependencies + +If a Helm chart has dependencies to other Helm charts, e.g. PostgreSQL, these dependencies **must** be specified in +the `Chart.yaml` file. Do not use outdated `requirements.yaml`. diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-02.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-02.md new file mode 100755 index 0000000..d3b4c33 --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-02.md @@ -0,0 +1,171 @@ +--- +title: PDG 5.02 - Chart structure +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------------------------| +| Draft | 17-Jul-2023 | templates/NOTES.txt made optional | +| Active | 10-Jan-2023 | add prerequisite and TL;DR as requirement in README.md | +| Active | 10-Nov-2022 | Initial release | + +## Why + +Following best practices when creating the chart helps everyone better understand, deploy and test the product. Having +similar structure for every Helm chart enables easy understand, simple implementation of testing and deployment workflows. + +Having the helm chart in the same directory than everyone else allows for easy finding the right helm chart. + +## Description + +Each Helm chart **should** follow a specific structure. Helm +provides [recommendations for creating charts](https://helm.sh/docs/chart_template_guide/getting_started/). + +For Eclipse Tractus-X Helm charts the following requirements **must** be met: + +- Helm chart location inside Git repository +- Helm chart file structure defined below + +### Chart Location + +Helm charts **must** be located inside the `/charts` directory of the Git repository. + +```text +charts/ + chartNameA/ + Chart.yaml + ... + chartNameB/ + Chart.yaml + ... +AUTHORS.md +DEPENDENCIES.md +LICENSE +README.md +``` + +For further details about the Git repository structure, please refer to [PDG 2.03 - Repo +Structure](../PDG%202%20-%20GIT/PDG-2-3.md). + +### Chart File Structure + +:::danger License/Copyright Headers required + +It is **mandatory to add a valid license/copyright header** to each file (except of rendered files, e.g. Markdown files) in the +Git repository! + +For further details, please refer to [How to make your Catena-X product OSS +ready](https://github.com/catenax-ng/foss-example#how-to-make-your-catenax-product-oss-ready). + +::: + +For Eclipse Tractus-X Helm charts we expect the following charts structure as a minimal set (except of optional parts): + +```text +chartName/ + .helmignore # mandatory + Chart.yaml # mandatory + LICENSE # mandatory + README.md # mandatory + values.yaml # mandatory + crds/ # optional + templates/ # mandatory, except of umbrella Helm charts + templates/NOTES.txt # optional +``` + +For further details on Helm chart basics, please refer to [Helm documentation](https://helm.sh/docs/topics/charts/). + +#### The `Chart.yaml` File + +The following represents the minimum set of expected fields in `Chart.yaml` file: + +```yaml +apiVersion: The chart API Version +name: The name of the chart +appVersion: The application version the chart will install +version: A SemVer 2 version of the chart +description: A brief description of the chart +home: The URL of the product home page +sources: + - A list of URLs to source code of this project +dependencies: # A list of the chart requirements (if any) + - name: The name of the chart + version: The version of the chart + repository: The repository URL +maintainers: # Optional, could become mandatory in Eclipse repositories + - name: Maintainers name + email: optional + url: A URL for the maintainer, optional +``` + +For further details about the `Chart.yaml` file please refer to [Helm +documentation](https://helm.sh/docs/topics/charts/#the-chartyaml-file). + +#### The `LICENSE` File + +The file **must** contain the [Apache 2.0 License](https://github.com/catenax-ng/foss-example/blob/main/general/LICENSE). + +#### The `README.md` File + +The README.md file **must** contain: + +- a brief explanation of what the Helm chart will install +- a section of "Prerequisites" includes the required kubernetes version, helm version and other necessary prerequisites and their versions. Example: + + ```markdown + - Kubernetes 1.19+ + - Helm 3.2.0+ + - PV provisioner support in the underlying infrastructure + ``` + +- a section of "TL;DR" that includes the helm commands to add and install the helm chart, Example: + + ```shell + helm repo add my-repo https://charts.bitnami.com/bitnami + helm install my-release my-repo/postgresql + ``` + +- documentation of default values for this Helm chart ([_helm-docs_](https://github.com/norwoodj/helm-docs#helm-docs) + may help). + +#### The `values.yaml` File + +The `values.yaml` file contains all necessary variables the Helm chart requires for successful installation. At the same +time this enables users to override the default values. + +For best practices on `values.yaml` files, please refer to [PDG 5.05 - Chart Values](PDG-5-05.md) or [Helm +documentation](https://helm.sh/docs/chart_template_guide/values_files/). + +:::caution multiple values files not allowed + +All default values **must** be introduced with `values.yaml` file to successfully install the Helm chart. + +There **must** be no additional `values-xyz.yaml` files, e.g. to specify environment specific values. Only `values.yaml` file +is allowed! +::: + +#### The `crds` Directory + +If the Helm chart installs custom resource definitions, this directory is the place to locate the manifest files in. + +For further details, refer to [Helm +documentation](https://helm.sh/docs/topics/charts/#custom-resource-definitions-crds). + +#### The `templates` Directory + +The `templates` directory contains manifest files, which will be deployed during Helm chart installation. For further +details, refer to [Helm documentation](https://helm.sh/docs/topics/charts/#template-files). + +#### The `templates/NOTES.txt` File + +The content of `templates/NOTES.txt` will be printed after Helm chart installation. The file is evaluated as a template +file with all possibilities of templating. + +#### `.helmignore` + +The `.helmignore` file should contain as a minimal set the following entries: + +```gitignore +# Accept only values.yaml +values?*.yaml +values?*.yml +``` diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-03.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-03.md new file mode 100755 index 0000000..ab0702f --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-03.md @@ -0,0 +1,38 @@ +--- +title: PDG 5.03 - Version strategy +--- + +| Status | Created | Post-History | +|--------|-------------|-----------------| +| Active | 10-Nov-2022 | Initial Release | + +## Why + +Correct versioning is crucial when testing and deploying the application. It helps to identify issues with the chart or +the application image. Upgrading or rolling back of the deployment would lead to problems without proper versioning. + +For more details, see the [official documentation](https://helm.sh/docs/topics/charts/#charts-and-versioning) + +## Description + +There are two different version properties for a Helm chart: + +- Chart version +- App version + +### Chart version + +It is located in the `Chart.yaml` under the `version` property. +It requires **semantic versioning** format. +The **Chart version has to be increased** every time one of the following file is changed: + +- `Chart.yaml` +- `values.yaml` +- templates directory + +### App version + +The default app version value is located in the `Chart.yaml` file under the **appVersion** property. Any format can be +used, but the appVersion and the image tag of your docker images should be aligned. This means, the appVersion should be +used in the templates as the **default image tag** for the deployment/pod. Every time the appVersion property is +upgraded the **chart version** number has to be increased as well. diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-04.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-04.md new file mode 100755 index 0000000..8e10b02 --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-04.md @@ -0,0 +1,24 @@ +--- +title: PDG 5.04 - Resource Management +--- + +| Status | Created | Post-History | +|--------|-------------|----------------------------------------------| +| Active | 23-Feb-2022 | Fix mixup between CPU and Memory description | +| Active | 10-Nov-2022 | Initial release | + +## Why + +To give guidance on kubernetes best practices and to match min. requirement when running an application. + +## Description + +The helm chart **must** contain app specific sane default CPU and Memory settings. + +## CPU + +Verify CPU is set to sane value and limit is 2-3 times higher (critical is that cpu request is not equal to limit). To have the CPU Limit higher than the request allows the pod to use more CPU when available and utilizes a node resources better. + +## Memory + +Verify that memory request and limit are set equal. Memory is not a 'stretchable' resource and kubernetes will delete a pod if it starts using more memory than expected. Setting the memory limit to a higher value allows it to have a hidden memory profile which might work as long as the node has enough memory and will destabilize when the node does not have enough memory anymore. diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-06.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-06.md new file mode 100755 index 0000000..dd3e936 --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-06.md @@ -0,0 +1,32 @@ +--- +title: PDG 5.06 - Application Configuration +--- + +| Status | Created | Post-History | +|--------|-------------|-----------------| +| Active | 30-Nov-2022 | Initial release | + +## Why + +The application will be deployed in different environments and application operators must be able to adjust the +deployment to environmental needs. + +## Description + +Every startup configuration aspect of your application **must** be configurable through your Helm chart. + +Examples for configurable items: + +- Ingress class, URLs and TLS configuration +- Resource annotations and labels +- Signing keys +- Database connection strings +- Secrets (with empty values!) +- Persistent storage configuration +- Environment variables (e.g. for application configuration) +- ... + +### Don'ts + +Required application rebuild for configuration (e.g. `applications.yaml` without the possibility to overwrite values via +env) changes are not expected. The application should be configurable and installable using the Helm chart. diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-07.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-07.md new file mode 100755 index 0000000..6fde3eb --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-07.md @@ -0,0 +1,52 @@ +--- +title: PDG 5.07 - Chart Dependencies +--- + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 07-Mar-2023 | | +| Draft | 02-Dec-2022 | n/a | + +## Why + +Dependencies like a database (postgresql) are used across Eclipse Tractus-X. It's critical to align those common dependencies when those dependencies are later replaced with hosted versions, like the database. Single instance of these dependencies that can be shared among all products in the future. + +## Description + +Helm chart dependencies are defined in the `Chart.yaml` file. They are used to provide additional software (e.g. database) that is required for running the main application. + +## Helm dependency example + +An example dependency definition in the `Chart.yaml` file: + +```yaml +dependencies: + - condition: postgresql.enabled + alias: product-name-postgresql + name: postgresql + repository: https://charts.bitnami.com/bitnami + version: 11.x.x +``` + +- Usage of condition, alias and version properties are optional but highly recommended +- Add a unique alias as name to your dependency that corresponds with your product name. This can be referenced in the `values.yaml` file +- With the condition, dependencies can be disabled/enabled on demand + +## Installing a chart with dependencies + +The following commands have to run before installing the chart if it has dependencies: + +```sh +helm repo add [REPO_URL] #for example: https://charts.bitnami.com/bitnami +helm dependency update +``` + +Then the install can be done with `helm install [NAME] [CHART] [flags]` + +## Aligning dependency versions + +The following table describes the required version of dependencies for all products. + +|Name |Repo URL |Chart version | App version| +|--- | --- | ---| ---| +|postgresql | [Bitnami](https://charts.bitnami.com/bitnami) | 11.x.x| 14.5.0| diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-08.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-08.md new file mode 100755 index 0000000..49ece1f --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-08.md @@ -0,0 +1,24 @@ +--- +title: PDG 5.08 - Product Helm Chart +--- + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 07-Mar-2023 | | +| Draft | 10-Jan-2023 | n/a | + +## Why + +Having a single source for Helm chart makes it easier to test and deploy the product and reduces the complexity of installing backend/frontend/utility applications separately. + +## Description + +A "Product Helm Chart" is a released helm chart that contains all the components of a product **ready to deploy**. This can either be achieved by **creating a single Helm chart** for the product or by **combining the Helm charts** of the different components into a single chart using dependencies. + +## Product Helm Chart rules + +- name of the Chart **should** be just the `product-name` without prefix or suffix (similar to the [leading product repository](../PDG%202%20-%20GIT/PDG-2-4)) +- values file **should** contain all available variables (even from subcharts) with default values and comments about what they do +- [helm install](https://helm.sh/docs/helm/helm_install/#helm-install) command should successfully install the chart to any supported Kubernetes version cluster (without overwriting default values) +- [helm test](https://helm.sh/docs/helm/helm_test/) runs without errors (see [PDG 5.09 - Helm test](PDG-5-09)) +- create a single helm chart for the whole product or combine charts into a single one using [dependencies](https://helm.sh/docs/helm/helm_dependency/#helm-dependency) feature diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-09.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-09.md new file mode 100755 index 0000000..c7347cf --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-09.md @@ -0,0 +1,133 @@ +--- +title: PDG 5.09 - Helm test PRERELEASE +--- + +:::caution +Proposed release date: "mandatory after": 19th of May 2023 +::: + +| Status | Created | Post-History | +|------------|-------------|--------------------| +| Prerelease | 7-Mar-2023 | Moved out of draft | +| Draft | 23-Feb-2023 | Draft release | + +## Why + +Helm charts are defined as the sane default for cloud native applications in Eclipse Tractus-X. To make sure that the aligned quality verification of applications are as close as possible to the production setup, +it is critical that the test setup is doing what it would do on a production setup. Therefore, Helm test will provide this mechanism together with kind and allows us to run e2e verifications directly on GitHub Actions. + +GitHub Actions simplifies the open source infrastructure requirements as otherwise a test k8s cluster would be required, which might not be available in the long run. + +This is the base for future e2e tests. + +This also allows to move the responsibility of verifing the helm chart functionality from the system team back to the development team. + +## Description + +Helm charts and their dependend images (the application to test) need to be validated by installing them and verifing that they are running successfully. + +Helm test is the technical solution helm provides to verify that a helm chart works as expected. It basically installs the helm chart (which installs and runs the application) and then allows an additional +container to run. This test container can do everything, especially calling an api, executing tests etc. + +This needs to be running in a Github Action in the repository which contains the Helm Chart, which gets released. + +Example Github Action Workflow: + +- Build all necessary container images / pull the container image under test +- Create [kind](https://kind.sigs.k8s.io/) setup (kind creates a kubernetes cluster through container images, github action supports this which allows you to create a kubernetes cluster inside the github action run) +- Make the necessary container images available through the kind setup (see github action example, it uses the local kind registry) +- Prepare and execute helm test +- Fail on a failing helm test + +Technical requirements: + +- A Github action exist which builds or uses the helm chart which gets released +- The Github action can be triggered manually through Github WebUI [manually running a workflow](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) +- Helm test verifies that the application is up and running + - Example verifications: + - Frontend: Frontend returns valid page + - API: API is reachable and returns valid response (access denied / test user can login) + +Example .github/workflows/helm-test.yaml + +```yaml +name: Lint and Test Charts + +on: + pull_request: + workflow_dispatch: + inputs: + node_image: + description: 'kindest/node image for k8s kind cluster' + # k8s version from 3.1 release as default + default: 'kindest/node:v1.24.6' + required: false + type: string + upgrade_from: + description: 'chart version to upgrade from' + # chart version from 3.1 release as default + default: 'x.x.x' + required: false + type: string + +jobs: + lint-test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Kubernetes KinD Cluster + uses: container-tools/kind-action@v1 + with: + # upgrade version, default (v0.17.0) uses node image v1.21.1 and doesn't work with more recent node image versions + version: v0.19.0 + # default value for event_name != workflow_dispatch + node_image: ${{ github.event.inputs.node_image || 'kindest/node:v1.24.6' }} + + - name: Build image + uses: docker/build-push-action@v3 + with: + context: . + push: true + tags: kind-registry:5000/app-dashboard:testing + + - name: Set up Helm + uses: azure/setup-helm@v3 + with: + version: v3.9.3 + + - uses: actions/setup-python@v4 + with: + python-version: '3.9' + check-latest: true + - name: Set up chart-testing + uses: helm/chart-testing-action@v2.3.1 + + - name: Run chart-testing (list-changed) + id: list-changed + run: | + changed=$(ct list-changed --target-branch ${{ github.event.repository.default_branch }}) + if [[ -n "$changed" ]]; then + echo "changed=true" >> $GITHUB_OUTPUT + fi + + - name: Run chart-testing (lint) + run: ct lint --validate-maintainers=false --target-branch ${{ github.event.repository.default_branch }} + - name: Run chart-testing (install) + run: ct install --charts charts/app-dashboard + if: github.event_name != 'pull_request' || steps.list-changed.outputs.changed == 'true' + + # Upgrade the released chart version with the locally available chart + # default value for event_name != workflow_dispatch + - name: Run helm upgrade + run: | + helm repo add bitnami https://charts.bitnami.com/bitnami + helm repo add tractusx-dev https://eclipse-tractusx.github.io/charts/dev + helm install [NAME] tractusx-dev/[CHART] --version ${{ github.event.inputs.upgrade_from || 'x.x.x' }} + helm dependency update charts/[CHART] + helm upgrade [NAME] charts/[CHART] + if: github.event_name != 'pull_request' || steps.list-changed.outputs.changed == 'true' +``` diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-10.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-10.md new file mode 100755 index 0000000..347f755 --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-10.md @@ -0,0 +1,52 @@ +--- +title: PDG 5.10 - Kubernetes versions PRERELEASE +--- + +:::caution +Proposed release date: "mandatory after": 19th of May 2023 +::: + +| Status | Created | Post-History | +|------------|-------------|--------------------| +| Prerelease | 7-Mar-2023 | Moved out of draft | +| Draft | 24-Feb-2022 | n/a | + +## Why + +New Kubernetes versions are [released](https://kubernetes.io/releases/) every few months. The compatibility with those versions needs to be verified as [APIs](https://kubernetes.io/docs/concepts/overview/kubernetes-api/) get deprecated. New Versions can also introduce issues. + +To make Eclipse Tractus-X usable in the industry, its necessary to support and test multiply versions of kubernetes (upcoming, stable, old). API deprecations are happening slowly but regularly. + +## Description + +To do so you **must** create a GitHub action which runs helm test against all required kubernetes versions. See the following PDG for an example GitHub action: [Helm test](PDG-5-09.md). + +The GitHub Action either can be **triggered manually** and allows for selecting the **kubernetes versions** or it verifies all required kubernetes versions one after the other. + +Products need to support 3 [versions](https://kubernetes.io/releases/) at a time: + +- latest +- latest - 1 +- latest - 2 + +## Testing compatibility locally + +For local deployment please see [Kind](https://kind.sigs.k8s.io/) clusters where a Kubernetes cluster can be started with a [specific version](https://kind.sigs.k8s.io/docs/user/configuration/#kubernetes-version) locally on a development machine. Example for example: + +```yaml +# config.yaml +kind: Cluster +apiVersion: kind.x-k8s.io/v1alpha4 +nodes: +- role: control-plane +- role: worker + image: kindest/node:v1.25.3@sha256:f1de3b0670462f43280114eccceab8bf1b9576d2afe0582f8f74529da6fd0365 +``` + +After Kind is installed locally, run the following command with the config above: + +```sh +kind create cluster --config=config.yaml +``` + +A Kubernetes node will start with version 1.25. diff --git a/docs/Guidelines/PDG_5_-_Helm/trg-5-11.md b/docs/Guidelines/PDG_5_-_Helm/trg-5-11.md new file mode 100755 index 0000000..c1022eb --- /dev/null +++ b/docs/Guidelines/PDG_5_-_Helm/trg-5-11.md @@ -0,0 +1,25 @@ +--- +title: PDG 5.11 - Upgradeability PRERELEASE +--- + +:::caution +Proposed release date: "mandatory after": 19th of May 2023 +::: + +| Status | Created | Post-History | +|------------|-------------|--------------------| +| Draft | 17-Jul-2023 | 'handels' typo fix | +| Prerelease | 7-Mar-2023 | Moved out of draft | +| Draft | 24-Feb-2022 | n/a | + +## Why + +With using helm charts, the upgrade of an application also happens through an upgrade of the helm chart. The application handles the upgrade itself like executing a database upgrade. The upgrade of the helm chart itself also needs to be tested and by testing the helm upgrade, you automatically verify that the application upgrade works too. + +## Description + +Based on the [Helm test](PDG-5-09.md) workflow, you **must** provide a GitHub action which takes the latest released helm chart, does an installation of it and then execute the upgrade to the current / new version. + +To do so you **must** provide a GitHub action which runs helm install of the last released version and than a helm upgrade of the version to be released and than execute a helm test. + +The **GitHub Action** needs to be able to be **triggered manually**. diff --git a/docs/Guidelines/PDG_6_-_Artefacts/assets/trg-6-1_chart_release_action_tag-error.png b/docs/Guidelines/PDG_6_-_Artefacts/assets/trg-6-1_chart_release_action_tag-error.png new file mode 100755 index 0000000..48ea594 Binary files /dev/null and b/docs/Guidelines/PDG_6_-_Artefacts/assets/trg-6-1_chart_release_action_tag-error.png differ diff --git a/docs/Guidelines/PDG_6_-_Artefacts/assets/trg-6-1_gh_pages_setup.png b/docs/Guidelines/PDG_6_-_Artefacts/assets/trg-6-1_gh_pages_setup.png new file mode 100755 index 0000000..ca76ed6 Binary files /dev/null and b/docs/Guidelines/PDG_6_-_Artefacts/assets/trg-6-1_gh_pages_setup.png differ diff --git a/docs/Guidelines/PDG_6_-_Artefacts/trg-6-1.md b/docs/Guidelines/PDG_6_-_Artefacts/trg-6-1.md new file mode 100755 index 0000000..b4e5e3f --- /dev/null +++ b/docs/Guidelines/PDG_6_-_Artefacts/trg-6-1.md @@ -0,0 +1,106 @@ +--- +title: PDG 6.01 - Released Helm Chart +--- + +| Status | Created | Post-History | +|--------|-------------|-----------------| +| Active | 01-Dec-2022 | Initial release | + +## Description + +A released Helm chart for each Tractus-X sub-product is expected to be available in corresponding GitHub repository. + +## Why + +Tractus-X components can only be used and bundled with other components of Tractus-X if there is a version of the +component with reliable content. This can only be achieved by creating a release of your Helm chart. We recommend to use +[GitHub Chart Releaser Action](https://github.com/marketplace/actions/helm-chart-releaser). + +### Process description + +If you follow this recommendation to use GitHub Chart Releaser Action to provide a released Helm Chart for your +Tractus-X sub-product, the process will provide the following for you: + +1. A GiHub Release is created with + - a GitHub release, named _Chartname-Semver_ (e.g. _productABC-0.1.1_) + - a Git tag _Chartname-Semver_ + - a release asset, containing the Helm chart files +2. A local Helm repository is created (file `index.yaml` in branch _gh-pages_) + +:::info + +Only if you follow this PDG to release a Helm Chart, the released Helm chart will be automatically added to +the [central Tractus-X Helm repository](https://eclipse-tractusx.github.io/charts/). + +::: + +### Prerequisites + +To get the GitHub Chart Releaser Action working, the following prerequisites must be met: + +- A branch named `gh-pages` in your repository +- Helm charts must be located in folder `/charts` +- A GitHub Actions Workflow (see section [Implementaion](#implementation)) + +### Implementation + +Create a GitHub Workflow file with following content: + +```yaml +name: Release - Helm Charts + +on: + push: + paths: + - 'charts/**' + branches: + - main +jobs: + release: + # depending on default permission settings for your org (contents being read-only or read-write for workloads), you will have to add permissions + # see: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token + permissions: + contents: write + runs-on: ubuntu-latest + + steps: + # fetch-depth: 0 is required to determine differences in chart(s) + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Configure Git + run: | + git config user.name "$GITHUB_ACTOR" + git config user.email "$GITHUB_ACTOR@users.noreply.github.com" + + - name: Install Helm + uses: azure/setup-helm@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Run chart-releaser + uses: helm/chart-releaser-action@v1.4.1 + env: + CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}" +``` + +Each time a changed Helm Chart is pushed (e.g. merge a PR) to _main_ branch, the workflow will be triggered. + +### Don'ts + +:::caution + +- Changing the `appVersion` requires also changing the `version` in `Chart.yaml` +- Chart `version` itself can be increased without changing the `appVersion` + +::: + +If the `appVersion` is increased, also the `version` in `Chart.yaml` must be increased, otherwise the workflow will +fail: + +![Chart Releaser Action - Tag error](assets/PDG-6-1_chart_release_action_tag-error.png) + +The Helm chart name and version is used for creating the Git Tag. As the Helm chart version did not increase, the +workflow tries to create a Git tag which already exists. diff --git a/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-0.md b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-0.md new file mode 100755 index 0000000..772eb33 --- /dev/null +++ b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-0.md @@ -0,0 +1,45 @@ +--- +title: PDG 7.00 - Recurring activities for each PR +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------| +| Active | 20-Jul-2023 | References to PDG 7.07, 7.08 updated | +| | 13-Apr-2023 | Moved from OSS Development | + +## Why + +Eclipse Tractus-X is an open source project hosted by the Eclipse Foundation licensed under the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0). The legal obligations of the content must be observed in all forms of which the content is available. + +:::info + +The requirements described here must be met for each contribution. + +::: + +## Description + +This is a summary of the most important requirements for OSS governance that you must follow. +Before submitting a PR, contributors should verify compliance with the requirements. The reviewing commiter can only accept a PR if it is compliant. + +### Keep the following updated when creating a CatenaX / Tractus-X relevant release tag + +- all requirements listed below +- IP checks for 3rd party content: **ALL** 3rd party content has the be approved by the Eclipse Foundation => in the DEPENDENCIES are only libraries with status "approved" + +### Keep the following updated for each pull request to the default branch (main) + +- Legal Documentation: [PDG 7.01](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-01) +- License and copyright header: [PDG 7.02](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-02) + - must be present in every file if possible + - update the year in the copyright section at the beginning of each new year +- IP checks for project content: [PDG 7.03](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-03) + - for each PR containing more than 1000 relevant lines there **must** be an approved [IP review for Code Contributions](/docs/oss/issues#eclipse-gitlab-ip-issue-tracker) before the contribution can be pushed/merged +- IP checks for 3rd party content: [PDG 7.04](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-04) + - DEPENDENCIES file is up-to-date and reflects the current use of the 3rd party content + - all libraries listed there should have the status "approved" + - no libraries with status "rejected" + - for libraries with status "restricted", the according IP issues must be present (issue number in the source column) +- Legal information for distributions: [PDG 7.05](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-05) +- Legal notice for end user content: [PDG 7.06](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-06) +- Legal notice for end user content: [PDG 7.07](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-07), [PDG 7.08](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-08) diff --git a/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-1.md b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-1.md new file mode 100755 index 0000000..db2ac00 --- /dev/null +++ b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-1.md @@ -0,0 +1,82 @@ +--- +title: PDG 7.01 - Legal Documentation +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------| +| Active | 24-Aug-2023 | Updated SECURITY.md file | +| Active | 20-Jul-2023 | References to PDG 7.07, 7.08 updated | +| Active | 13-Apr-2023 | Moved from OSS Development | + +## Why + +Eclipse Tractus-X is an open source project hosted by the Eclipse Foundation licensed under the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0). The legal obligations of the content must be observed in all forms of which the content is available. + +This page contains information about legal documentation requirements in your repositories. The source of truth is always the [Eclipse Foundation Project Handbook](https://www.eclipse.org/projects/handbook/#legaldoc). + +:::info + +The requirements described here **must** be met for each contribution. + +::: + +## Description + +The following files must be part of your repository root folder: + +- LICENSE +- SECURITY.md +- CONTRIBUTING.md +- CODE_OF_CONDUCT.md + +For examples look to the [Eclipse Tractus-X GitHub Organisation](https://github.com/eclipse-tractusx), e.g. the [APP Dashboard](https://github.com/eclipse-tractusx/app-dashboard). + +### LICENSE FILE + +In Eclipse Tractus-X the primary outbound license is Apache-2.0. + +- SPDX-License-Identifier: Apache-2.0 +- [License Text](https://www.apache.org/licenses/LICENSE-2.0.txt) + +See the [Handbook#legaldoc-license](https://www.eclipse.org/projects/handbook/#legaldoc-license). + +For specifically defined documentation files the Creative Commons Attribution 4.0 International (CC BY 4.0) is required, see PDG 7.08. + +### SECURITY FILE + +The security file contain the information, where/how to report a vulnerability issue. +See the [Handbook#vulnerability](https://www.eclipse.org/projects/handbook/#vulnerability) and this [example](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/main/SECURITY.md). + +Content: + +```md +## Reporting a Vulnerability + +Please do **not** report security vulnerabilities through public GitHub issues. + +Please report vulnerabilities to this repository via **GitHub security advisories** instead. + +How? Inside affected repository --> security tab + +for contributor: +--> Report a vulnerability + +for committer: +--> advisories --> New draft security advisory + +In severe cases, you can also report a found vulnerability via mail or eclipse issue here: https://www.eclipse.org/security/ + +See [Eclipse Foundation Vulnerability Reporting Policy](https://www.eclipse.org/projects/handbook/#vulnerability) +``` + +### CODE OF CONDUCT + +:::info + +The Version 2.0 of the Eclipse Foundation Community Code of Conduct was released on Jan 01, 2023. +Update the file in your repositories. + +::: + +See the [CODE OF CONDUCT](https://www.eclipse.org/org/documents/Community_Code_of_Conduct.php) +and here in [md format](https://raw.githubusercontent.com/eclipse/.github/master/CODE_OF_CONDUCT.md). diff --git a/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-2.md b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-2.md new file mode 100755 index 0000000..ad4635a --- /dev/null +++ b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-2.md @@ -0,0 +1,83 @@ +--- +title: PDG 7.02 - License and Copyright header +--- + +| Status | Created | Post-History | +|--------|-------------|----------------------------| +| Active | 13-Apr-2023 | Moved from OSS Development | + +## Why + +Eclipse Tractus-X is an open source project hosted by the Eclipse Foundation licensed under the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0). The legal obligations of the content must be observed in all forms of which the content is available. + +This page contains information about legal documentation requirements in your files. The source of truth is always the [Eclipse Foundation Project Handbook](https://www.eclipse.org/projects/handbook/#ip-copyright-headers). + +:::info + +The requirements described here **must** be met for each contribution. + +::: + +## Description + +*Where possible, all source code, property files, and metadata files (including application, test, and generated source code as well as other types of files such as XML, HTML, etc.) should contain appropriate copyright and license notices as well as information on each contribution.* (From the [Handbook#ip-copyright-headers](https://www.eclipse.org/projects/handbook/#ip-copyright-headers)) + +:::caution + +Update the year in the copyright header at the start of each new year! + +Example: +Copyright (c) 202x, **``** Contributors to the Eclipse Foundation + +::: + +### Copyright and License Header + +Example (Java): + +```md +/******************************************************************************** + * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation + * + * See the NOTICE file(s) distributed with this work for additional + * information regarding copyright ownership. + * + * This program and the accompanying materials are made available under the + * terms of the Apache License, Version 2.0 which is available at + * https://www.apache.org/licenses/LICENSE-2.0. + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + * + * SPDX-License-Identifier: Apache-2.0 + ********************************************************************************/ + ``` + +:::tip + +Use your IDE's template mechanism to add the text automatically when you create new files. + +::: + +#### Copyright Header + +You can also **add** the following line (one or more times) to identify the specific copyright owner(s): + +Copyright (c) 202x,20yy {owner}[ and others] + +Examples: + +1. Copyright (c) 2021,2023 MyCompany GmbH + - 2021, 2023 means from 2021 to 2023 + - Copyright: MyCompany GmbH +1. Copyright (c) 2021,2023 MyCompany GmbH and others + - others: somebody has made minor changes (e.g. fixed typos) + +Do **not** remove the general line "Copyright (c) 202x,20yy Contributors to the Eclipse Foundation". + +#### License Header + +Never change the license section, except for the formatting characters for the appropriate language. diff --git a/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-3.md b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-3.md new file mode 100755 index 0000000..a9ffc29 --- /dev/null +++ b/docs/Guidelines/PDG_7_-_Open_Source_Governance/pdg-7-3.md @@ -0,0 +1,116 @@ +--- +title: PDG 7.07 - Legal notice for non-code (e.g. documentation) +--- + +| Status | Created | Post-History | +|--------|-------------|------------------------------| +| Active | 18-Jul-2023 | Update: improved description | +| | 13-Apr-2023 | Initial version | + +## Why + +Eclipse Tractus-X is an open source project hosted by the Eclipse Foundation licensed under the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0). The legal obligations of the content must be observed in all forms of which the content is available. + +All products delivered by the project—including websites, documentation, slides and help must include certain notices. Documentation might include a notice in either the pre- or post-amble, or a website might provide this information in a common footer, or a dedicated page. (From: [Eclipse Foundation Project Handbook](https://www.eclipse.org/projects/handbook/#legaldoc-end-user)) + +## Description + +Eclipse Tractus-X allows two outbound licenses: Apache-2.0 and CC-BY-4.0. +The outbound license is the `LICENSE` that resides at the root level of each repository. Unless otherwise noted, this is the default license for all self-created artifacts in the repository. For all repositories containing code, this is the Apache-2.0 license. An example for a repository licensed under the CC-BY-4.0 are the [semantic models](https://github.com/eclipse-tractusx/sldt-semantic-models). + +In this PDG, by non-code artifacts we mean documentation and images embedded in this documentation. All of these artifacts have to include notices about copyright, license and source location information. Excluded are the [legal documenation files](/docs/Release%20Guidelines/PDG%207%20-%20Open%20Source%20Governance/PDG-7-01#description). + +There are special cases for the **KIT documentation**, that have to be licensed under the CC-BY-4.0, see PDG 7-08. + +## Location of secondary licenses + +If you use more then one outbound license, you have to put the "second" license to a `LICENSES/` directory.
+Naming: `.txt` + +**Example:** Apache-2.0 as default license, CC-BY-4.0 as second license + +```shell +project/ +|__ LICENSE (<- Apache-2.0) +|__ LICENSES/ +| |__ CC-BY-4.0.txt +| ... +``` + +## How to include legal notices + +:::tip +Think about "old-fashioned" printed documents:
+Attributions for non-code artefacts, like documentation files, have to be visible for the reciever, that means +it has to be added to the content, **NOT** in comments, metadata, or alt text (images). +::: + +### Documentation + +In this chapter we show an example of how to do it for the md format licensed under the Apache-2.0, for other formats like slides, pdf, and others the format may be slightly different. + +Add a `NOTICE` section (post or preamble) into your dedicated documentation file, with the following information: + +```text +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 202x,202y +- SPDX-FileCopyrightText: 202x,202y Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/ + ``` + +:::tip +If there are multiple copyright holders, insert several SPDX-FileCopyrightText lines, for each entry one line. Explanations in brackets, do not copy. PLEASE. + +- SPDX-FileCopyrightText: 2022,2023 MyCompany (-> MyCompany contributed from 2022 to 2023) +- SPDX-FileCopyrightText: 2021,2022 YourCompany (-> YourCompany contributed from 2021 to 2022) +- SPDX-FileCopyrightText: 2023 ThirdCompany (-> ThirdCompany contributed only in 2023) +- SPDX-FileCopyrightText: 2020,2023 AnotherCompany (-> AnotherCompany contributed from 2020 to 2023) +- SPDX-FileCopyrightText: 2021,2023 Contributors to the Eclipse Foundation +::: + +### Self-created images + +Self-created images have as default license the license at root level of your repository (as long you followed the guidelines of having a `LICENSES` directory for secondary licenses). + +If your documenation file and the images are in the same repository and have the default license and authorship/copyright is covered by the git history, the NOTICE section above is sufficient. + +If not, please see PDG 7.08. + +### Third-party content + +If you embed third-party content (images) in your artefacts, the images have to be attributed with th following informations: + +- Title +- Author/Copyright +- License +- Source + +#### Where to put the attribution + +- right next to, over or under the image +- **OR** make a clear reference to it and put the attribution in the NOTICE section + +**Example - photo with attribution:** + +![example](@site/static/img/oss_example_Creative_Commons_10th_Birthday.jpg) + +Direct attribution: + +["Creative Commons 10th Birthday Celebration San Francisco"](http://www.flickr.com/photos/sixteenmilesofstring/8256206923/in/set-72157632200936657) by [Timothy Vollmer](http://www.flickr.com/photos/sixteenmilesofstring/) is licensed under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/) + +Section for the notice file: + +```text +### Third-party content + +- Title: "Creative Commons 10th Birthday Celebration San Francisco" +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: [Timothy Vollmer](https://www.flickr.com/photos/sixteenmilesofstring/) +- Source URL: https://www.flickr.com/photos/sixteenmilesofstring/8256206923/in/set-72157632200936657 + ``` + +See more: [https://wiki.creativecommons.org/wiki/best_practices_for_attribution](https://wiki.creativecommons.org/wiki/best_practices_for_attribution) diff --git a/docs/Guidelines/index.md b/docs/Guidelines/index.md new file mode 100644 index 0000000..8232887 --- /dev/null +++ b/docs/Guidelines/index.md @@ -0,0 +1,22 @@ +# Developer Guidelines + +## Introduction + +Welcome to pmoscode developer guidelines, known as PDGs. PDG numbers — once assigned — never change, and each PDG deals with special technical topics. + +You find the overarching Changelog [here](PDG_0_-_Changelog & Drafts) to see when new PDGs have been added. + +## Goal + +This PDG's main goal is: Providing reasonable defaults for requirements, components and styles. +This shall make contribution, maintenance and running products/components as easy as possible. + +## Living documentation + +Adding new PDG's is the simplest case. Here they are just added and the history is updated. + +Once in "active" status, changing or deleting PDG's does not delete the obsolete content. Rather, these are optically "deleted" and, if necessary, supplemented with new content. + +## Contribution + +If you want to contribute to this PDG or you recognize typos or mistakes, feel free to crate a Pull Request! diff --git a/docs/assets/logo-icon-round-inverted.png b/docs/assets/logo-icon-round-inverted.png new file mode 100644 index 0000000..3b237f2 Binary files /dev/null and b/docs/assets/logo-icon-round-inverted.png differ diff --git a/docs/assets/logo-icon-round.png b/docs/assets/logo-icon-round.png new file mode 100644 index 0000000..ff0f131 Binary files /dev/null and b/docs/assets/logo-icon-round.png differ diff --git a/docs/fonts/lato/lato-v24-latin-300.ttf b/docs/fonts/lato/lato-v24-latin-300.ttf new file mode 100644 index 0000000..f49dd5c Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-300.woff2 b/docs/fonts/lato/lato-v24-latin-300.woff2 new file mode 100644 index 0000000..aad98a3 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-300italic.ttf b/docs/fonts/lato/lato-v24-latin-300italic.ttf new file mode 100644 index 0000000..84ea014 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300italic.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-300italic.woff2 b/docs/fonts/lato/lato-v24-latin-300italic.woff2 new file mode 100644 index 0000000..394b5cf Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300italic.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-700.ttf b/docs/fonts/lato/lato-v24-latin-700.ttf new file mode 100644 index 0000000..0dc02c9 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-700.woff2 b/docs/fonts/lato/lato-v24-latin-700.woff2 new file mode 100644 index 0000000..11de83f Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-700italic.ttf b/docs/fonts/lato/lato-v24-latin-700italic.ttf new file mode 100644 index 0000000..02a862b Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700italic.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-700italic.woff2 b/docs/fonts/lato/lato-v24-latin-700italic.woff2 new file mode 100644 index 0000000..38df58b Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700italic.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-regular.ttf b/docs/fonts/lato/lato-v24-latin-regular.ttf new file mode 100644 index 0000000..85b2663 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-regular.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-regular.woff2 b/docs/fonts/lato/lato-v24-latin-regular.woff2 new file mode 100644 index 0000000..ff60934 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-regular.woff2 differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2fa6bd5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,13 @@ +# Introduction + +Welcome to the **Developer Hub** of pmoscode for Helm charts / Docker image repositories! + +Here you will find all the information +you need for an uncomplicated contribution in the pmoscode Helm chart organization. + +Of course, these are not always applicable in all cases. +For most cases, however, +they make it easier to process pull requests and help maintain a consolidated repository landscape. + +This makes it easier for you to understand the structure and elements of the Helm charts +and to contribute to this organization. diff --git a/docs/style/extra.css b/docs/style/extra.css new file mode 100644 index 0000000..fd7ba69 --- /dev/null +++ b/docs/style/extra.css @@ -0,0 +1,54 @@ +/* lato-300 - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: normal; + font-weight: 300; + src: url('/fonts/lato/lato-v24-latin-300.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-300.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-300italic - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: italic; + font-weight: 300; + src: url('/fonts/lato/lato-v24-latin-300italic.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-300italic.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-regular - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: normal; + font-weight: 400; + src: url('/fonts/lato/lato-v24-latin-regular.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-regular.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-700 - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: normal; + font-weight: 700; + src: url('/fonts/lato/lato-v24-latin-700.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-700.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-700italic - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: italic; + font-weight: 700; + src: url('/fonts/lato/lato-v24-latin-700italic.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-700italic.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + + +:root { + --md-text-font: "Lato"; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e20691c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,76 @@ +# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json + +site_name: Developer Hub + +#custom_dir: overrides + +theme: + name: material + logo: assets/logo-icon-round-inverted.png + font: false + features: + - navigation.instant + - navigation.tracking + - navigation.indexes + - navigation.top + - search.highlight + - navigation.footer + - content.code.copy + - content.code.annotate + palette: + - scheme: default + primary: deep orange + accent: blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: deep orange + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + +plugins: + - search +# - privacy: +# assets: true +# assets_fetch: true +# assets_fetch_dir: assets/external + +extra_css: + - style/extra.css + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/pmoscode + - icon: fontawesome/brands/docker + link: https://hub.docker.com/u/pmoscode + - icon: fontawesome/regular/envelope + link: mailto:info@pmoscode.de + consent: + title: Cookie consent + description: >- + We use cookies to recognize your repeated visits and preferences, as well + as to measure the effectiveness of our documentation and whether users + find what they're searching for. With your consent, you're helping us to + make our documentation better. + actions: + - accept + - reject + +copyright: > + Copyright © 2023 pmoscode – + Change cookie settings + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - admonition + - pymdownx.details + - pymdownx.snippets + - pymdownx.superfences