index.md 10.1 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

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

## Design Choices

13
In order to easily support SSH replicas, and avoid using shared storage for the SSH
14 15 16
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
| Parameter                | Default        | Description                              |
| ------------------------ | -------------- | ---------------------------------------- |
| `annotations`            |                | Pod annotations                          |
29
| `config.loginGraceTime`  | `120`          | Specifies amount of time athat the server will disconnect after if the user has not successfully logged in |
30
| `config.maxStartups.full`  | `100`     | SSHd refuse probability will increase linearly and all unauthenticated connection attempts would be refused when unauthenticated connections number will reach specified number |
31
| `config.maxStartups.rate`  | `30`      | SSHd will refuse connections with specified probability when there would be too many unauthenticated connections (optional) |
32
| `config.maxStartups.start` | `10`      | SSHd will refuse connection attempts with some probability if there are currently more than the specified number of unauthenticated connections (optional) |
33 34 35 36 37
| `deployment.livenessProbe.initialDelaySeconds` | 10 | Delay before liveness probe is initiated |
| `deployment.livenessProbe.periodSeconds`  | 10 | How often to perform the liveness probe |
| `deployment.livenessProbe.timeoutSeconds` | 3 | When the liveness probe times out |
| `deployment.livenessProbe.successThreshold` | 1 | Minimum consecutive successes for the liveness probe to be considered successful after having failed |
| `deployment.livenessProbe.failureThreshold` | 3 | Minimum consecutive failures for the liveness probe to be considered failed after having succeeded |
38
| `enabled`                | `true`         | Shell enable flag                        |
39 40
| `extraContainers`        |                | List of extra containers to include      |
| `extraInitContainers`    |                | List of extra init containers to include |
41
| `extraVolumeMounts`      |                | List of extra volumes mounts to do       |
42 43 44 45 46 47
| `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                          |
48 49
| `init.image.repository`  |                | initContainer image                      |
| `init.image.tag`         |                | initContainer image tag                  |
50 51
| `redis.serviceName`      | `redis`        | Redis service name                       |
| `replicaCount`           | `1`            | Shell replicas                           |
52
| `service.externalTrafficPolicy` | `Cluster` | Shell service external traffic policy (Cluster or Local)  |
53 54
| `service.externalPort`   | `22`           | Shell exposed port                       |
| `service.internalPort`   | `22`           | Shell internal port                      |
55
| `service.nodePort`       |                | Sets shell nodePort if set               |
56 57 58 59
| `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)  |
60
| `service.type`           | `ClusterIP`    | Shell service type                       |
Mike Rennie's avatar
Mike Rennie committed
61
| `tolerations`            | `[]`           | Toleration labels for pod assignment     |
Evan Read's avatar
Evan Read committed
62
| `workhorse.serviceName`    | `unicorn`      | Workhorse service name (by default, Workhorse is a part of the Unicorn Pods / Service)                   |
Mike Rennie's avatar
Mike Rennie committed
63

64
## Chart configuration examples
65

66 67
### image.pullSecrets

68 69 70 71 72 73
`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`:
74

75
```yaml
76 77 78 79
image:
  repository: my.shell.repository
  tag: latest
  pullPolicy: Always
80
  pullSecrets:
81 82 83 84
  - name: my-secret-name
  - name: my-secondary-secret-name
```

Mike Rennie's avatar
Mike Rennie committed
85
### tolerations
86

Mike Rennie's avatar
Mike Rennie committed
87 88 89
`tolerations` allow you schedule pods on tainted worker nodes

Below is an example use of `tolerations`:
90 91

```yaml
Mike Rennie's avatar
Mike Rennie committed
92 93 94 95 96 97 98 99 100 101 102
tolerations:
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoExecute"
```

103
### annotations
104

105
`annotations` allows you to add annotations to the GitLab Shell pods.
106 107

Below is an example use of `annotations`
108

109
```yaml
110 111
annotations:
  kubernetes.io/example-annotation: annotation-value
112
```
113

114 115
## External Services

Dmitry Chepurovskiy's avatar
Dmitry Chepurovskiy committed
116 117
This chart should be attached the Workhorse service, and should also use the same Redis
as the attached Workhorse service.
118 119 120

### Redis

121
```yaml
122
redis:
123
  host: redis.example.com
124 125
  serviceName: redis
  port: 6379
126 127 128
  sentinels:
    - host: sentinel1.example.com
      port: 26379
129 130 131 132 133
  password:
    secret: gitlab-redis
    key: redis-password
```

134 135 136 137 138 139 140 141 142
| 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`. If using Redis Sentinels, the `host` attribute needs to be set to the cluster name as specified in the `sentinel.conf`.|
| `password.key`      | String  |         | The name of the key in the secret below that contains the password. |
| `password.secret`   | String  |         | The name of the Kubernetes `Secret` to pull from. |
| `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. |
| `sentinels.[].host` | String  |         | The hostname of Redis Sentinel server for a Redis HA setup. |
| `sentinels.[].port` | Integer | `26379` | The port on which to connect to the Redis Sentinel server. |
143 144 145

_Note:_ The current Redis Sentinel support only supports Sentinels that have
been deployed separately from the GitLab chart. As a result, the Redis
Gerard Hickey's avatar
Gerard Hickey committed
146 147 148
deployment through the GitLab chart should be disabled with `redis.install=false`.
The Secret containing the Redis password will need to be manually created
before deploying the GitLab chart.
149

Dmitry Chepurovskiy's avatar
Dmitry Chepurovskiy committed
150
### Workhorse
151

152
```yaml
Dmitry Chepurovskiy's avatar
Dmitry Chepurovskiy committed
153 154
workhorse:
  host: workhorse.example.com
155
  serviceName: unicorn
156
  port: 8181
157 158
```

159 160
| Name          | Type    | Default   | Description |
|:--------------|:-------:|:----------|:------------|
Dmitry Chepurovskiy's avatar
Dmitry Chepurovskiy committed
161
| `host`        | String  |           | The hostname of the Workhorse server. This can be omitted in lieu of `serviceName`. |
162
| `port`        | Integer | `8181`    | The port on which to connect to the Workhorse server.|
Dmitry Chepurovskiy's avatar
Dmitry Chepurovskiy committed
163
| `serviceName` | String  | `unicorn` | The name of the `service` which is operating the Workhorse server. By default, Workhorse is a part of the Unicorn Pods / Service. 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 Workhorse as a part of the overall GitLab chart. |
164 165 166 167 168

## Chart Settings

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

169
### hostKeys.secret
170

171 172
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.
173

174
### authToken
175

Dmitry Chepurovskiy's avatar
Dmitry Chepurovskiy committed
176 177
GitLab Shell uses an Auth Token in its communication with Workhorse. Share the token
with GitLab Shell and Workhorse using a shared Secret.
178

179
```yaml
180 181 182 183 184
authToken:
 secret: gitlab-shell-secret
 key: secret
```

185 186 187 188
| Name               | Type    | Default | Description |
|:-------------------|:-------:|:--------|:------------|
| `authToken.key`    | String  |         | The name of the key in the above secret that contains the auth token. |
| `authToken.secret` | String  |         | The name of the Kubernetes `Secret` to pull from. |
189 190 191 192 193 194 195 196 197 198 199 200

### 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)

201
```yaml
202 203 204 205 206 207 208
service:
  type: LoadBalancer
  loadBalancerIP: 1.2.3.4
  loadBalancerSourceRanges:
  - 5.6.7.8/32
  - 10.0.0.0/8
```