diff --git a/docs/reference/concepts/_category_.json b/docs/reference/concepts/_category_.json index f46e44eeb2..e22fb3427a 100644 --- a/docs/reference/concepts/_category_.json +++ b/docs/reference/concepts/_category_.json @@ -1 +1 @@ -{ "label": "Concepts", "position": 4, "collapsed": true } +{ "label": "Concepts", "position": 8, "collapsed": true } diff --git a/docs/reference/concepts/git-config-flow.png b/docs/reference/concepts/git-config-flow.png new file mode 100644 index 0000000000..584278967f Binary files /dev/null and b/docs/reference/concepts/git-config-flow.png differ diff --git a/docs/reference/concepts/git_configuration.md b/docs/reference/concepts/git_configuration.md index b5ce0a00ff..702bb04510 100644 --- a/docs/reference/concepts/git_configuration.md +++ b/docs/reference/concepts/git_configuration.md @@ -11,32 +11,25 @@ doc-topic: [epinio, reference, concepts, git-configuration] ## Overview -Starting with version **1.10.0**, Epinio supports Git configurations. - Configurations enable cloning of private repositories, disabling of SSL verification, and/or extending verification through a custom bundle of certificates. -This is done on a per git host (+user/org, +repository) basis. - -Management, including creation, is done through the -[epinio gitconfig](../cli/gitconfig/epinio_gitconfig.md) -command ensemble. - -## Matching process +For GitHub and GitLab instances you create a git configuration with a username and +password/token, and optionally the skip-SSL-verification and global flags. A **global** +configuration can be used by any user; a non-global one is visible and usable only to the user who +created it and to administrators. Only administrators may create a global configuration. -When importing from a git repository Epinio will use the most specific matching configuration, if -there is any. +For the `git`, GitHub Enterprise (Cloud and Self-Hosted), and GitLab Enterprise types the same +fields are available plus a **git host** field, where you enter the instance URL. -This means that a matching configuration specifying url, user/organization, and repository has -priority over matching configurations specifying only url and user/organization, or even just the -url. +You attach a configuration to an application by **selecting it** when you set the application's Git +source. Epinio does not implicitly match a configuration to a repository URL; the selection is +explicit, and a private repository will fail to clone if no usable configuration is selected. -If no configuration is found then the cloning from the Git repository will run without any -customization. -## Github/Gitlab specialities +## Github/Gitlab Specialities -The public Github and Gitlab mega repositories support the use of a `PAT` (Personal Access Token) +The public Github and Gitlab repositories support the use of a `PAT` (Personal Access Token) over a plain combination of user and password. When using a PAT it has to be set as the password, and the user can be set to anything except empty. @@ -45,76 +38,52 @@ When using a PAT it has to be set as the password, and the user can be set to an For reference, it is useful to set it to the username used to generate the token. ::: -## Detailed specification +## Enterprise and self-hosted instances -:::note -This section contains information useful to operators for debugging and inspection. -Regular users should not normally need to consult this section. -::: +The enterprise and generic `git` types take a **git host** URL in addition to the credential +fields: + +- **GitHub Enterprise Self-Hosted** (`github_enterprise_self_hosted`): enter the instance host URL + (for example `https://github.mycorp.com`). Epinio appends the GitHub Enterprise Server REST path + (`/api/v3`). +- **GitHub Enterprise Cloud** (`github_enterprise_cloud`): enter the API host URL for your + Enterprise Cloud instance, for example `https://api.github.com`, or `https://api..ghe.com` + for a data-residency instance. Epinio uses it as given. +- **GitLab Enterprise** (`gitlab_enterprise`) and generic **Git** (`git`): enter the instance host + URL. GitLab is accessed under `/api/v4`. + +## Detailed Specification A Git configuration is a Kubernetes secret with the `epinio.io/api-git-credentials: "true"` label. The fields are: -|Field |Required|Meaning | -|--- |--- |--- | -|`url` |yes | the host of the git instance | -|`provider` | | one of `github`, `gitlab`, `git`, `github_enterprise`, `gitlab_enterprise` | -|`username` | | used during the Basic Authentication | -|`password` | | used during the Basic Authentication | -|`userOrg` | | used to restrict the configuration to a specific organization/project | -|`repo` | | used to restrict the configuration to a specific repository | -|`skipSSL` | | used to skip the SSL verification | -|`certificate` | | the CA bundle to load for the SSL verification with self-signed certificates | - -All the fields, except for the URL, are optional. - -## Example: - -Invoking the commands - -```bash -cat > certfile < For more examples check the [How-to](../../how-to/developer/concepts/git_configuration.md). diff --git a/docs/reference/customization/_category_.json b/docs/reference/customization/_category_.json index 27e3404da1..002554ab3a 100644 --- a/docs/reference/customization/_category_.json +++ b/docs/reference/customization/_category_.json @@ -1 +1 @@ -{ "label": "Customization", "position": 5, "collapsed": true } +{ "label": "Customization", "position": 9, "collapsed": true } diff --git a/docs/reference/detailed-push-process.md b/docs/reference/detailed-push-process.md index 62ae3b6217..b9f212b58c 100644 --- a/docs/reference/detailed-push-process.md +++ b/docs/reference/detailed-push-process.md @@ -1,5 +1,6 @@ --- sidebar_label: "Epinio push process" +sidebar_position: 6 title: "The Epinio push process in detail" description: The Epinio push process in detail keywords: [epinio, kubernetes, push process] diff --git a/docs/reference/principles.md b/docs/reference/principles.md index 359dcdbbc0..9770654b64 100644 --- a/docs/reference/principles.md +++ b/docs/reference/principles.md @@ -1,5 +1,6 @@ --- sidebar_label: "Principles" +sidebar_position: 7 title: "Epinio design principles" description: The design principles Epinio is based upon. keywords: [epinio, kubernetes, design principles] diff --git a/docs/reference/security/_category_.json b/docs/reference/security/_category_.json index b821a3e992..cd8dd76a63 100644 --- a/docs/reference/security/_category_.json +++ b/docs/reference/security/_category_.json @@ -1 +1 @@ -{ "label": "Security & auth", "position": 6, "collapsed": true } +{ "label": "Security & auth", "position": 10, "collapsed": true } diff --git a/docs/reference/upgrading.md b/docs/reference/upgrading.md index 2bc803891e..f7ab85d956 100644 --- a/docs/reference/upgrading.md +++ b/docs/reference/upgrading.md @@ -1,6 +1,6 @@ --- sidebar_label: Upgrading Epinio -sidebar_position: 8 +sidebar_position: 5 title: Upgrading Epinio description: Breaking changes and migration steps when upgrading Epinio between versions. keywords: [epinio, upgrade, migration, breaking changes, versions] @@ -13,6 +13,29 @@ Review the breaking changes and migration steps for your target version before upgrading. For the full list of releases and their release notes, see [versions](../versions.md). +## 1.13.X and 1.14.0 to 1.14.1 + +Git configuration handling changed. Selecting a configuration when deploying from a **private** +repository is now **explicit**: Epinio no longer implicitly matches a stored configuration to a +repository URL at push time. + +- **New private-repo pushes must select a git configuration.** In the dashboard, choose one in the + application's Git source. From the CLI or automation, the git origin must carry + `origin.git.gitconfig`; a push that sends no configuration clones unauthenticated and fails with + `authentication required`. +- **Existing applications keep working.** On redeploy, a compatibility fallback still matches + configuration-less apps to a stored configuration by repository URL, so they continue to clone as + before. +- **Credentials are bound to their instance host.** A configuration's credentials are only sent to + the host it is scoped to; selecting a configuration whose host does not match the repository is + rejected. +- **Global configurations are administrator-only to create.** Non-admin users can use global + configurations but cannot create them. + +This release also adds a `spec.origin.git.gitconfig` field to the `apps` CRD. If you install CRDs +from the Helm chart's `crds/` directory out of band, apply the updated CRD on upgrade so the field +is not pruned. See [Git Configuration](./concepts/git_configuration.md). + ## 1.13.X to 1.14.0 There are no breaking changes in this release. Documentation around performance was