forked from vmware-archive/gangway
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4 from numberly/mkdocs
Switch to Mkdocs documentation
- Loading branch information
Showing
30 changed files
with
816 additions
and
90 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,96 +1,18 @@ | ||
| # Welcome to Numberly/Gangway a new fork with multi-cluster improvements | ||
| # Gangway by Numberly | ||
|
|
||
| Gangway is EOL but still used at Numberly, we decided to fork and maintain it. | ||
| ## Introduction | ||
|
|
||
| See the original repository : https://github.com/vmware-archive/gangway | ||
| Welcome to Numberly/Gangway, a maintained fork of the original Gangway project, now End-Of-Life (EOL). It simplifies authentication flows using OpenID Connect (OIDC) for Kubernetes clusters, focusing on multi-cluster support. | ||
|
|
||
| This fork aims to continue development of Gangway by Numberly corporation. | ||
| ## Features | ||
|
|
||
| gangway | ||
| ======= | ||
| - **Multi-Cluster Management**: Manages multiple clusters to reduce complexity. | ||
| - **OIDC Authentication**: Streamlines ID token minting for Kubernetes API server access. | ||
|
|
||
| _(noun): An opening in the bulwark of the ship to allow passengers to board or leave the ship._ | ||
| ## Documentation | ||
|
|
||
| An application that can be used to easily enable authentication flows via OIDC for a kubernetes cluster. | ||
| Kubernetes supports [OpenID Connect Tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) as a way to identify users who access the cluster. | ||
| Gangway has been improved and is now able to handle multiple clusters | ||
| Gangway allows users to self-configure their `kubectl` configuration in a few short steps. | ||
| Checkout the [GANGWAY Documentation](https://link-to-doc.numberly.com) | ||
|
|
||
|  | ||
| ## Building from Source | ||
|
|
||
| Once authenticated for one of your cluster : | ||
|
|
||
|  | ||
|
|
||
| ## Deployment | ||
|
|
||
| Instructions for deploying gangway for common cloud providers can be found [here](docs/README.md). | ||
|
|
||
| We can use our dedicated helm chart that will allow you to configure Gangway easily [here](chart/README.md) | ||
|
|
||
| ## The multi-cluster way | ||
|
|
||
| At Numberly, initially, we was deploying 1 gangway per cluster which could lead to a lot of WebUI to connect | ||
| our clusters. One of the goal of the fork was also to permit to Gangway to manage any clusters to facilitate | ||
| our management. Gangway can now take a configuration with environment and a list of cluster for each environments. | ||
| You can read more about it [here](docs/configuration.md) | ||
|
|
||
| ## How It Works | ||
|
|
||
| Kubernetes supports OpenID Connect (OIDC) as a user authentication mechanism. OIDC is an | ||
| authentication protocol that allows servers to verify the identity of a user by way of an ID Token. | ||
|
|
||
| When using OIDC to authenticate with Kubernetes, the client (e.g. `kubectl`) sends the ID token | ||
| alongside all requests to the API server. On the server side, the Kubernetes API server verifies the | ||
| token to ensure it is valid and has not expired. Once verified, the API server extracts username and | ||
| group membership information from the token, and continues processing the request. | ||
|
|
||
| In order to obtain the ID token, the user must go through the OIDC authentication process. This is | ||
| where Gangway comes in. Gangway is a web application that enables the OIDC authentication flow which | ||
| results in the minting of the ID Token. | ||
|
|
||
| Gangway is configured as a client of an upstream Identity Service that speaks OIDC. To obtain the ID | ||
| token, the user accesses Gangway, initiates the OIDC flow by clicking the "Log In" button, and | ||
| completes the flow by authenticating with the upstream Identity Service. The user's credentials are | ||
| never shared with Gangway. | ||
|
|
||
| Once the authentication flow is complete, the user is redirected to a Gangway page that provides | ||
| instructions on how to configure `kubectl` to use the ID token. | ||
|
|
||
| The following sequence diagram details the authentication flow: | ||
|
|
||
| <p align="center"> | ||
| <img src="docs/images/gangway-sequence-diagram.png" width="600px" /> | ||
| </p> | ||
|
|
||
| ## API-Server flags | ||
|
|
||
| gangway requires that the Kubernetes API server is configured for OIDC: | ||
|
|
||
| https://kubernetes.io/docs/admin/authentication/#configuring-the-api-server | ||
|
|
||
| ```bash | ||
| kube-apiserver | ||
| ... | ||
| --oidc-issuer-url="https://example.auth0.com/" | ||
| --oidc-client-id=3YM4ue8MoXgBkvCIHh00000000000 | ||
| --oidc-username-claim=email | ||
| --oidc-groups-claim=groups | ||
| ``` | ||
|
|
||
| ## Build | ||
|
|
||
| Requirements for building | ||
|
|
||
| - Go (built with version >= 1.21) | ||
|
|
||
| A Makefile is provided for building tasks. The options are as follows | ||
|
|
||
| Getting started is as simple as: | ||
|
|
||
| ```bash | ||
| go get -u github.com/soulkyu/gangway | ||
| cd $GOPATH/src/github.com/soulkyu/gangway | ||
| make setup | ||
| make | ||
| ``` | ||
| Written in Go (83.9%). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| ## Paramètres du serveur API | ||
|
|
||
| Gangway nécessite que le serveur API Kubernetes soit configuré pour OIDC : | ||
|
|
||
| [https://kubernetes.io/docs/admin/authentication/#configuring-the-api-server](https://kubernetes.io/docs/admin/authentication/#configuring-the-api-server) | ||
|
|
||
| ```bash | ||
| kube-apiserver | ||
| ... | ||
| --oidc-issuer-url="https://example.auth0.com/" | ||
| --oidc-client-id=3YM4ue8MoXgBkvCIHh00000000000 | ||
| --oidc-username-claim=email | ||
| --oidc-groups-claim=groups | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| ## API-Server flags | ||
|
|
||
| gangway requires that the Kubernetes API server is configured for OIDC: | ||
|
|
||
| https://kubernetes.io/docs/admin/authentication/#configuring-the-api-server | ||
|
|
||
| ```bash | ||
| kube-apiserver | ||
| ... | ||
| --oidc-issuer-url="https://example.auth0.com/" | ||
| --oidc-client-id=3YM4ue8MoXgBkvCIHh00000000000 | ||
| --oidc-username-claim=email | ||
| --oidc-groups-claim=groups | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| ## Construction | ||
|
|
||
| Exigences pour la construction | ||
|
|
||
| - Go (construit avec la version >= 1.21) | ||
|
|
||
| Un Makefile est fourni pour les tâches de construction. Les options sont les suivantes : | ||
|
|
||
| Pour commencer, c'est aussi simple que : | ||
|
|
||
| ```bash | ||
| go get -u github.com/soulkyu/gangway | ||
| cd $GOPATH/src/github.com/soulkyu/gangway | ||
| make setup | ||
| make | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| ## Build | ||
|
|
||
| Requirements for building | ||
|
|
||
| - Go (built with version >= 1.21) | ||
|
|
||
| A Makefile is provided for building tasks. The options are as follows | ||
|
|
||
| Getting started is as simple as: | ||
|
|
||
| ```bash | ||
| go get -u github.com/soulkyu/gangway | ||
| cd $GOPATH/src/github.com/soulkyu/gangway | ||
| make setup | ||
| make | ||
| ``` |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| # Déploiement de Gangway | ||
|
|
||
| Le déploiement de Gangway consiste à écrire un fichier de configuration, puis à déployer le service. | ||
| Le service est sans état, il est donc relativement facile à gérer sur Kubernetes. | ||
| La manière dont vous fournirez l'accès au service dépendra de votre configuration spécifique. | ||
|
|
||
| Gangway est maintenant conscient d'une configuration multi-cluster, nous avons développé un chart Helm qui facilitera le déploiement. | ||
|
|
||
| Voici un exemple de configuration : | ||
|
|
||
| ```yaml | ||
| host: 0.0.0.0 | ||
| port: 8080 | ||
| serveTLS: false | ||
| clusters: | ||
| Production: | ||
| - EnvPrefix: kube01 | ||
| apiServerURL: https://kube01-api-url:443 | ||
| audience: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| providerURL: https://accounts.google.com | ||
| clientID: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| clientSecret: GXXXX-XXXXXXXXXXXXXXXXXXX | ||
| clusterName: kube01 | ||
| emailClaim: email | ||
| redirectURL: https://gangway.local/callback | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| tokenURL: https://www.googleapis.com/oauth2/v4/token | ||
| usernameClaim: email | ||
| Development: | ||
| - EnvPrefix: kube02 | ||
| apiServerURL: https://kube02-api-url:443 | ||
| audience: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| providerURL: https://accounts.google.com | ||
| clientID: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| clientSecret: GXXXX-XXXXXXXXXXXXXXXXXXX | ||
| clusterName: kube02 | ||
| emailClaim: email | ||
| redirectURL: https://gangway.local/callback | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| tokenURL: https://www.googleapis.com/oauth2/v4/token | ||
| usernameClaim: email | ||
| - EnvPrefix: kube03 | ||
| apiServerURL: https://kube03-api-url:443 | ||
| audience: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| providerURL: https://accounts.google.com | ||
| clientID: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| clientSecret: GXXXX-XXXXXXXXXXXXXXXXXXX | ||
| clusterName: kube03 | ||
| emailClaim: email | ||
| redirectURL: https://gangway.local/callback | ||
| clusterCAPath: /etc/gangly/pki/kube03/ca.crt | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| tokenURL: https://www.googleapis.com/oauth2/v4/token | ||
| usernameClaim: email | ||
| ``` |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| # Configuration du Chart Helm pour Gangway | ||
|
|
||
| Ce document décrit les paramètres configurables du chart Helm pour Gangway et leurs valeurs par défaut. | ||
|
|
||
| ## Paramètres Globaux | ||
|
|
||
| - `global.imageRegistry` : Registre global d'images Docker (par défaut : `""`) | ||
| - `global.imagePullSecrets` : Noms des secrets de registre Docker global sous forme de tableau (par défaut : `[]`) | ||
| - `global.storageClass` : Classe de stockage globale pour le(s) volume(s) persistant(s) (par défaut : `""`) | ||
|
|
||
| ## Paramètres Communs | ||
|
|
||
| - `kubeVersion` : Forcer la version cible de Kubernetes (par défaut : `""`) | ||
| - `nameOverride` : Chaîne pour remplacer partiellement le modèle `common.names.fullname` (par défaut : `""`) | ||
| - `fullnameOverride` : Chaîne pour remplacer entièrement le modèle `common.names.fullname` (par défaut : `""`) | ||
| - `commonLabels` : Étiquettes à ajouter à tous les objets déployés (par défaut : `{}`) | ||
| - `commonAnnotations` : Annotations à ajouter à tous les objets déployés (par défaut : `{}`) | ||
| - `clusterDomain` : Domaine de cluster Kubernetes par défaut (par défaut : `cluster.local`) | ||
| - `extraDeploy` : Tableau d'objets supplémentaires à déployer avec la release (par défaut : `[]`) | ||
|
|
||
| ## Paramètres de l'Image Gangway | ||
|
|
||
| - `image.registry` : Registre d'image Gangway (par défaut : `docker.io`) | ||
| - `image.repository` : Dépôt d'image Gangway (par défaut : `numberlyinfra/gangway`) | ||
| - `image.tag` : Tag de l'image Gangway (par défaut : `master`) | ||
| - `image.digest` : Digest de l'image Gangway (par défaut : `""`) | ||
| - `image.pullPolicy` : Politique de téléchargement de l'image (par défaut : `Always`) | ||
| - `image.pullSecrets` : Spécifier les noms des secrets de registre Docker sous forme de tableau (par défaut : `[]`) | ||
| - `image.debug` : Activer le mode debug de l'image Gangway (par défaut : `false`) | ||
|
|
||
| ## Paramètres de Déploiement de Gangway | ||
|
|
||
| - `replicaCount` : Nombre de répliques de Gangway à déployer (par défaut : `3`) | ||
| - `updateStrategy.type` : StrategyType peut être défini sur `RollingUpdate` ou `OnDelete` (par défaut : `RollingUpdate`) | ||
| - `podSecurityContext.enabled` : Activer le contexte de sécurité des pods Gangway (par défaut : `true`) | ||
| - `podSecurityContext.fsGroup` : ID de groupe pour les volumes du pod (par défaut : `1001`) | ||
| - `containerSecurityContext.enabled` : Activer le contexte de sécurité des conteneurs Gangway (par défaut : `true`) | ||
| - `containerSecurityContext.runAsUser` : ID utilisateur pour exécuter les conteneurs Gangway (par défaut : `1001`) | ||
| - `containerSecurityContext.runAsNonRoot` : Définir le contexte de sécurité du conteneur Gangway runAsNonRoot (par défaut : `true`) | ||
| - `resources.limits` : Les limites de ressources pour le conteneur Gangway (par défaut : `{}`) | ||
| - `resources.requests` : Les ressources demandées pour le conteneur Gangway (par défaut : `{ memory: "512Mi", cpu: "300m" }`) | ||
|
|
||
| ## Probes | ||
|
|
||
| - `startupProbe.enabled` : Activer startupProbe (par défaut : `false`) | ||
| - `livenessProbe.enabled` : Activer livenessProbe (par défaut : `true`) | ||
| - `readinessProbe.enabled` : Activer readinessProbe (par défaut : `true`) | ||
|
|
||
| ## Configuration du Service | ||
|
|
||
| - `service.type` : Type de service Kubernetes (par défaut : `ClusterIP`) | ||
| - `service.ports.http` : Port HTTP du service (par défaut : `8080`) | ||
| - `service.sessionAffinity` : Affinité de session pour le service Kubernetes (par défaut : `ClientIP`) | ||
|
|
||
| ## Configuration de l'Ingress | ||
|
|
||
| - `ingress.enabled` : Définir sur true pour activer la génération de l'enregistrement d'ingress (par défaut : `false`) | ||
| - `ingress.hostname` : Hôte par défaut pour la ressource ingress (par défaut : `gangway.local`) | ||
| - `ingress.path` : Le chemin vers Gangway (par défaut : `/`) | ||
| - `ingress.annotations` : Annotations supplémentaires pour la ressource Ingress (par défaut : `{}`) | ||
|
|
||
| ## Configuration Supplémentaire | ||
|
|
||
| - `extraEnvVars` : Variables d'environnement supplémentaires à définir sur le conteneur Gangway (par défaut : `[]`) | ||
| - `extraVolumes` : Spécifier éventuellement une liste supplémentaire de volumes pour les pods Gangway (par défaut : `[]`) | ||
| - `extraVolumeMounts` : Spécifier éventuellement une liste supplémentaire de volumeMounts pour le(s) conteneur(s) Gangway (par défaut : `[]`) | ||
|
|
||
| ## Affinité et Tolérances | ||
|
|
||
| - `podAffinityPreset` : Préréglage d'affinité de pod (par défaut : `""`) | ||
| - `podAntiAffinityPreset` : Préréglage d'anti-affinité de pod (par défaut : `soft`) | ||
| - `nodeAffinityPreset.type` : Type de préréglage d'affinité de nœud (par défaut : `""`) | ||
| - `affinity` : Affinité pour l'assignation de pod (par défaut : `{}`) | ||
| - `nodeSelector` : Étiquettes de nœud pour l'assignation de pod (par défaut : `{}`) | ||
| - `tolerations` : Tolérances pour l'assignation de pod (par défaut : `[]`) | ||
|
|
||
| ## Personnalisation | ||
|
|
||
| - `command` : Remplacer la commande par défaut du conteneur (par défaut : `[]`) | ||
| - `args` : Remplacer les arguments par défaut du conteneur (par défaut : `[]`) | ||
| - `lifecycleHooks` : pour le(s) conteneur(s) Gangway afin d'automatiser la configuration avant ou après le démarrage (par défaut : `{}`) | ||
| - `extraEnvVarsCM` : Nom du ConfigMap existant contenant des variables d'environnement supplémentaires (par défaut : `""`) | ||
| - `extraEnvVarsSecret` : Nom du Secret existant contenant des variables d'environnement supplémentaires (par défaut : `""`) | ||
|
|
||
| ## Session et Configuration | ||
|
|
||
| - `sessionkey` : Clé de session (par défaut : `mySessionKey`) | ||
| - `sessionsalt` : Sel de session (par défaut : `mySessionSalt`) | ||
| - `configuration` : Configuration en ligne pour Gangway (par défaut : `""`) | ||
|
|
||
| ## Exemple de configuration : | ||
| ```yaml | ||
| host: 0.0.0.0 | ||
| port: 8080 | ||
| serveTLS: false | ||
| clusters: | ||
| Production: | ||
| - EnvPrefix: kube01 | ||
| apiServerURL: https://kube01-api-url:443 | ||
| audience: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| providerURL: https://accounts.google.com | ||
| clientID: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| clientSecret: GXXXX-XXXXXXXXXXXXXXXXXXX | ||
| clusterName: kube01 | ||
| emailClaim: email | ||
| redirectURL: https://gangway.local/callback | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| tokenURL: https://www.googleapis.com/oauth2/v4/token | ||
| usernameClaim: email | ||
| Development: | ||
| - EnvPrefix: kube02 | ||
| apiServerURL: https://kube02-api-url:443 | ||
| audience: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| providerURL: https://accounts.google.com | ||
| clientID: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| clientSecret: GXXXX-XXXXXXXXXXXXXXXXXXX | ||
| clusterName: kube02 | ||
| emailClaim: email | ||
| redirectURL: https://gangway.local/callback | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| tokenURL: https://www.googleapis.com/oauth2/v4/token | ||
| usernameClaim: email | ||
| - EnvPrefix: kube03 | ||
| apiServerURL: https://kube03-api-url:443 | ||
| audience: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| providerURL: https://accounts.google.com | ||
| clientID: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com | ||
| clientSecret: GXXXX-XXXXXXXXXXXXXXXXXXX | ||
| clusterName: kube03 | ||
| emailClaim: email | ||
| redirectURL: https://gangway.local/callback | ||
| clusterCAPath: /etc/gangly/pki/kube03/ca.crt | ||
| scopes: | ||
| - openid | ||
| - profile | ||
| tokenURL: https://www.googleapis.com/oauth2/v4/token | ||
| usernameClaim: email | ||
| ``` | ||
| To get more informations : [Configuration](configuration.md) |
Oops, something went wrong.