index.md 7.71 KB
Newer Older
1 2
# Using the GitLab-Shell chart

3
The `gitlab-shell` sub-chart provides an SSH server configured for Git SSH access to GitLab.
4 5 6

## Requirements

7 8 9
This chart depends on access to Redis and Unicorn services, either as part of the
complete GitLab chart or provided as external services reachable from the Kubernetes
cluster this chart is deployed onto.
10 11 12

## Design Choices

13 14 15 16
In order to easily support SSH replicas, and avoid using shared storage for the ssh
authorized keys, we are using the SSH [AuthorizedKeysCommand](https://man.openbsd.org/sshd_config#AuthorizedKeysCommand)
to authenticate against GitLab's authorized keys endpoint. As a result, we don't persist
or update the AuthorizedKeys file within these pods.
17

18
## Configuration
19

20 21 22
The `gitlab-shell` chart is configured in two parts: [external services](#external-services),
and [chart settings](#chart-settings). The port exposed through Ingress is configured
with `global.shell.port`, and defaults to `22`.
23

24 25
## Installation command line options

26 27 28 29 30 31
| Parameter                | Default        | Description                              |
| ------------------------ | -------------- | ---------------------------------------- |
| `annotations`            |                | Pod annotations                          |
| `enabled`                | `true`         | Shell enable flag                        |
| `extraContainers`        |                | List of extra containers to include      |
| `extraInitContainers`    |                | List of extra init containers to include |
32
| `extraVolumeMounts`      |                | List of extra volumes mounts to do       |
33 34 35 36 37 38 39 40 41 42 43 44
| `extraVolumes`           |                | List of extra volumes to create          |
| `hpa.targetAverageValue` | `100m`         | Set the autoscaling target value         |
| `image.pullPolicy`       | `Always`       | Shell image pull policy                  |
| `image.pullSecrets`      |                | Secrets for the image repository         |
| `image.repository`       | `registry.com/gitlab-org/build/cng/gitlab-shell` | Shell image repository |
| `image.tag`              | `latest`       | Shell image tag                          |
| `init.image`             | `busybox`      | initContainer image                      |
| `init.tag`               | `latest`       | initContainer image tag                  |
| `redis.serviceName`      | `redis`        | Redis service name                       |
| `replicaCount`           | `1`            | Shell replicas                           |
| `service.externalPort`   | `22`           | Shell exposed port                       |
| `service.internalPort`   | `22`           | Shell internal port                      |
45 46 47 48
| `service.name`           | `gitlab-shell` | Shell service name                       |
| `service.type`           | `ClusterIP`    | Shell service type                       |
| `service.loadBalancerIP` |                | IP address to assign to LoadBalancer (if supported) |
| `service.loadBalancerSourceRanges` |      | List of IP CIDRs allowed access to LoadBalancer (if supported)  |
49
| `service.type`           | `ClusterIP`    | Shell service type                       |
Mike Rennie's avatar
Mike Rennie committed
50
| `tolerations`            | `[]`           | Toleration labels for pod assignment     |
51
| `unicorn.serviceName`    | `unicorn`      | Unicorn service name                     |
Mike Rennie's avatar
Mike Rennie committed
52

53
## Chart configuration examples
54

55 56
### image.pullSecrets

57 58 59 60 61 62
`pullSecrets` allows you to authenticate to a private registry to pull images for a pod.

Additional details about private registries and their authentication methods can be
found in [the Kubernetes documentation](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod).

Below is an example use of `pullSecrets`:
63

64
```yaml
65 66 67 68
image:
  repository: my.shell.repository
  tag: latest
  pullPolicy: Always
69
  pullSecrets:
70 71 72 73
  - name: my-secret-name
  - name: my-secondary-secret-name
```

Mike Rennie's avatar
Mike Rennie committed
74
### tolerations
75

Mike Rennie's avatar
Mike Rennie committed
76 77 78
`tolerations` allow you schedule pods on tainted worker nodes

Below is an example use of `tolerations`:
79 80

```yaml
Mike Rennie's avatar
Mike Rennie committed
81 82 83 84 85 86 87 88 89 90 91
tolerations:
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoExecute"
```

92
### annotations
93

94
`annotations` allows you to add annotations to the GitLab Shell pods.
95 96

Below is an example use of `annotations`
97

98
```yaml
99 100
annotations:
  kubernetes.io/example-annotation: annotation-value
101
```
102

103 104
## External Services

105 106
This chart should be attached the Unicorn service, and should also use the same Redis
as the attached Unicorn service.
107 108 109

### Redis

110
```yaml
111
redis:
112
  host: redis.example.com
113 114 115 116 117 118 119
  serviceName: redis
  port: 6379
  password:
    secret: gitlab-redis
    key: redis-password
```

120 121 122 123
| Name            | Type    | Default | Description |
|:----------------|:-------:|:--------|:------------|
| host            | String  |         | The hostname of the Redis server with the database to use. This can be omitted in lieu of `serviceName`. |
| password.key    | String  |         | The name of the key in the secret below that contains the password. |
124
| password.secret | String  |         | The name of the Kubernetes `Secret` to pull from. |
125 126
| port            | Integer | `6379`  | The port on which to connect to the Redis server. |
| serviceName     | String  | `redis` | The name of the `service` which is operating the Redis database. If this is present, and `host` is not, the chart will template the hostname of the service (and current `.Release.Name`) in place of the `host` value. This is convenient when using Redis as a part of the overall GitLab chart. |
127 128 129

### Unicorn

130
```yaml
131
unicorn:
132
  host: unicorn.example.com
133
  serviceName: unicorn
134 135 136
  port: 8080
```

137 138 139 140 141
| Name        | Type    | Default   | Description |
|:------------|:-------:|:----------|:------------|
| host        | String  |           | The hostname of the Unicorn server. This can be omitted in lieu of `serviceName`. |
| port        | Integer | `8080`    | The port on which to connect to the Unicorn server.|
| serviceName | String  | `unicorn` | The name of the `service` which is operating the Unicorn server. If this is present, and `host` is not, the chart will template the hostname of the service (and current `.Release.Name`) in place of the `host` value. This is convenient when using Unicorn as a part of the overall GitLab chart. |
142 143 144 145 146

## Chart Settings

The following values are used to configure the GitLab Shell Pods.

147
### hostKeys.secret
148

149 150
The name of the Kubernetes `secret` to grab the SSH host keys from. The keys in the
secret must start with the key names `ssh_host_` in order to be used by GitLab Shell.
151

152
### authToken
153

154 155
GitLab Shell uses an Auth Token in its communication with Unicorn. Share the token
with GitLab Shell and Unicorn using a shared Secret.
156

157
```yaml
158 159 160 161 162
authToken:
 secret: gitlab-shell-secret
 key: secret
```

163 164 165
| Name             | Type    | Default | Description |
|:-----------------|:-------:|:--------|:------------|
| authToken.key    | String  |         | The name of the key in the above secret that contains the authToken. |
166
| authToken.secret | String  |         | The name of the Kubernetes `Secret` to pull from. |
167 168 169 170 171 172 173 174 175 176 177 178

### LoadBalancer Service

If the `service.type` is set to `LoadBalancer`, you can optionally specify `service.loadBalancerIP` to create
the `LoadBalancer` with a user-specified IP (if your cloud provider supports it).

You can also optionally specify a list of `service.loadBalancerSourceRanges` to restrict
the CIDR ranges that can access the `LoadBalancer` (if your cloud provider supports it).

Additional information about the `LoadBalancer` service type can be found in
[the Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/#loadbalancer)

179
```yaml
180 181 182 183 184 185 186
service:
  type: LoadBalancer
  loadBalancerIP: 1.2.3.4
  loadBalancerSourceRanges:
  - 5.6.7.8/32
  - 10.0.0.0/8
```