BigW Consortium Gitlab

Skip to content

G
gitlab-ce
Commit be9e5ce3 by Achilleas Pipinellis
Options

Merge branch 'docs/gke-cluster' into 'master'

Add docs for GKE integration See merge request gitlab-org/gitlab-ce!14712
parents 10d41a9c d9526d1d
Showing with 172 additions and 59 deletions
doc/integration/google.md
# Google OAuth2 OmniAuth Provider
To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use.
1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab.
1. Select "Create Project".
1. Provide the project information
- Project name: 'GitLab' works just fine here.
- Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one.
1. Refresh the page. You should now see your new project in the list. Click on the project.
1. Select the "Google APIs" tab in the Overview.
1. Select and enable the following Google APIs - listed under "Popular APIs"
- Enable `Contacts API`
- Enable `Google+ API`
To enable the Google OAuth2 OmniAuth provider you must register your application
with Google. Google will generate a client ID and secret key for you to use.
## Enabling Google OAuth
In Google's side:
1. Navigate to the [cloud resource manager](https://console.cloud.google.com/cloud-resource-manager) page
1. Select **Create Project**
1. Provide the project information:
- **Project name** - "GitLab" works just fine here.
- **Project ID** - Must be unique to all Google Developer registered applications.
Google provides a randomly generated Project ID by default. You can use
the randomly generated ID or choose a new one.
1. Refresh the page and you should see your new project in the list
1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard)
1. Select the previously created project form the upper left corner
1. Select **Credentials** from the sidebar
1. Select **OAuth consent screen** and fill the form with the required information
1. In the **Credentials** tab, select **Create credentials > OAuth client ID**
1. Fill in the required information
- **Application type** - Choose "Web Application"
- **Name** - Use the default one or provide your own
- **Authorized JavaScript origins** -This isn't really used by GitLab but go
ahead and put `https://gitlab.example.com`
- **Authorized redirect URIs** - Enter your domain name followed by the
callback URIs one at a time:
1. Select "Credentials" in the submenu.
```
https://gitlab.example.com/users/auth/google_oauth2/callback
https://gitlab.exampl.com/-/google_api/auth/callback
```
1. Select "Create New Client ID".
1. You should now be able to see a Client ID and Client secret. Note them down
or keep this page open as you will need them later.
1. From the **Dashboard** select **ENABLE APIS AND SERVICES > Google Cloud APIs > Container Engine API > Enable**
1. Fill in the required information
- Application type: "Web Application"
- Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here.
- Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback'
1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration. ![Google app](img/google_app.png)
On your GitLab server:
1. On your GitLab server, open the configuration file.
1. Open the configuration file.
For omnibus package:
For Omnibus GitLab:
```sh
sudo editor /etc/gitlab/gitlab.rb
sudo editor /etc/gitlab/gitlab.rb
```
For installations from source:
```sh
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
1. Add the provider configuration:
1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
1. Add the provider configuration:
For omnibus package:
For Omnibus GitLab:
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "google_oauth2",
"app_id" => "YOUR_APP_ID",
"app_secret" => "YOUR_APP_SECRET",
"args" => { "access_type" => "offline", "approval_prompt" => '' }
}
]
gitlab_rails['omniauth_providers'] = [
{
"name" => "google_oauth2",
"app_id" => "YOUR_APP_ID",
"app_secret" => "YOUR_APP_SECRET",
"args" => { "access_type" => "offline", "approval_prompt" => '' }
}
]
```
For installations from source:
```
- { name: 'google_oauth2', app_id: 'YOUR_APP_ID',
app_secret: 'YOUR_APP_SECRET',
args: { access_type: 'offline', approval_prompt: '' } }
- { name: 'google_oauth2', app_id: 'YOUR_APP_ID',
app_secret: 'YOUR_APP_SECRET',
args: { access_type: 'offline', approval_prompt: '' } }
```
1. Change 'YOUR_APP_ID' to the client ID from the Google Developer page from step 10.
1. Change 'YOUR_APP_SECRET' to the client secret from the Google Developer page from step 10.
1. Make sure that you configure GitLab to use an FQDN as Google will not accept raw IP addresses.
1. Change `YOUR_APP_ID` to the client ID from the Google Developer page
1. Similarly, change `YOUR_APP_SECRET` to the client secret
1. Make sure that you configure GitLab to use an FQDN as Google will not accept
raw IP addresses.
For Omnibus packages:
```ruby
external_url 'https://gitlab.example.com'
external_url 'https://gitlab.example.com'
```
For installations from source:
......@@ -88,21 +97,32 @@ To enable the Google OAuth2 OmniAuth provider you must register your application
```
1. Save the configuration file.
1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
installed GitLab via Omnibus or from source respectively.
On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in.
On the sign in page there should now be a Google icon below the regular sign in
form. Click the icon to begin the authentication process. Google will ask the
user to sign in and authorize the GitLab application. If everything goes well
the user will be returned to GitLab and will be signed in.
## Further Configuration
This further configuration is not required for Google authentication to function but it is strongly recommended. Taking these steps will increase usability for users by providing a little more recognition and branding.
At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable.
1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window).
1. Scroll down until you find "Product Name". Change the product name to something more descriptive.
1. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users.
This further configuration is not required for Google authentication to function
but it is strongly recommended. Taking these steps will increase usability for
users by providing a little more recognition and branding.
At this point, when users first try to authenticate to your GitLab installation
with Google they will see a generic application name on the prompt screen. The
prompt informs the user that "Project Default Service Account" would like to
access their account. "Project Default Service Account" isn't very recognizable
and may confuse or cause users to be concerned. This is easily changeable:
1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for
instructions on how to get here if you closed your window).
1. Scroll down until you find "Product Name". Change the product name to
something more descriptive.
1. Add any additional information as you wish - homepage, logo, privacy policy,
etc. None of this is required, but it may help your users.
[reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
[restart GitLab]: ../administration/restart_gitlab.md#installations-from-source
doc/user/permissions.md
......@@ -76,6 +76,7 @@ The following table depicts the various user permission levels in a project.
| Force push to protected branches [^4] | | | | | |
| Remove protected branches [^4] | | | | | |
| Remove pages | | | | | ✓ |
| Manage clusters | | | | ✓ | ✓ |
## Project features permissions
......
doc/user/project/clusters/index.md 0 → 100644
# Connecting GitLab with GKE
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in 10.1.
CAUTION: **Warning:**
The Cluster integration is currently in **Beta**.
Connect your project to Google Container Engine (GKE) in a few steps.
With a cluster associated to your project, you can use Review Apps, deploy your
applications, run your pipelines, and much more in an easy way.
NOTE: **Note:**
The Cluster integration will eventually supersede the
[Kubernetes integration](../integrations/kubernetes.md). For the moment,
you can create only one cluster.
## Prerequisites
In order to be able to manage your GKE cluster through GitLab, the following
prerequisites must be met:
- The [Google authentication integration](../../../integration/google.md) must
be enabled in GitLab at the instance level. If that's not the case, ask your
administrator to enable it.
- Your associated Google account must have the right privileges to manage
clusters on GKE. That would mean that a
[billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
must be set up.
- You must have Master [permissions] in order to be able to access the **Cluster**
page.
If all of the above requirements are met, you can proceed to add a new cluster.
## Adding a cluster
NOTE: **Note:**
You need Master [permissions] and above to add a cluster.
To add a new cluster:
1. Navigate to your project's **CI/CD > Cluster** page.
1. Connect your Google account if you haven't done already by clicking the
"Sign-in with Google" button.
1. Fill in the requested values:
- **Cluster name** (required) - The name you wish to give the cluster.
- **GCP project ID** (required) - The ID of the project you created in your GCP
console that will host the Kubernetes cluster. This must **not** be confused
with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
- **Zone** - The zone under which the cluster will be created. Read more about
[the available zones](https://cloud.google.com/compute/docs/regions-zones/).
- **Number of nodes** - The number of nodes you wish the cluster to have.
- **Machine type** - The machine type of the Virtual Machine instance that
the cluster will be based on. Read more about [the available machine types](https://cloud.google.com/compute/docs/machine-types).
- **Project namespace** - The unique namespace for this project. By default you
don't have to fill it in; by leaving it blank, GitLab will create one for you.
1. Click the **Create cluster** button.
After a few moments your cluster should be created. If something goes wrong,
you will be notified.
Now, you can proceed to [enable the Cluster integration](#enabling-or-disabling-the-cluster-integration).
## Enabling or disabling the Cluster integration
After you have successfully added your cluster information, you can enable the
Cluster integration:
1. Click the "Enabled/Disabled" switch
1. Hit **Save** for the changes to take effect
You can now start using your Kubernetes cluster for your deployments.
To disable the Cluster integration, follow the same procedure.
## Removing the Cluster integration
NOTE: **Note:**
You need Master [permissions] and above to remove a cluster integration.
NOTE: **Note:**
When you remove a cluster, you only remove its relation to GitLab, not the
cluster itself. To remove the cluster, you can do so by visiting the GKE
dashboard or using `kubectl`.
To remove the Cluster integration from your project, simply click on the
**Remove integration** button. You will then be able to follow the procedure
and [add a cluster](#adding-a-cluster) again.
[permissions]: ../../permissions.md
doc/user/project/index.md
......@@ -63,6 +63,8 @@ common actions on issues or merge requests
browse, and download job artifacts
- [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job),
timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more
- [GKE cluster integration](clusters/index.md): Connecting your GitLab project
with Google Container Engine
- [GitLab Pages](pages/index.md): Build, test, and deploy your static
website with GitLab Pages
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment