index.md 9.03 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
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 29
| Parameter                | Default        | Description                              |
| ------------------------ | -------------- | ---------------------------------------- |
| `annotations`            |                | Pod annotations                          |
| `enabled`                | `true`         | Shell enable flag                        |
30 31 32 33 34
| `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 |
35 36
| `extraContainers`        |                | List of extra containers to include      |
| `extraInitContainers`    |                | List of extra init containers to include |
37
| `extraVolumeMounts`      |                | List of extra volumes mounts to do       |
38 39 40 41 42 43 44 45 46 47 48 49
| `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                      |
50 51 52 53
| `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)  |
54
| `service.type`           | `ClusterIP`    | Shell service type                       |
Mike Rennie's avatar
Mike Rennie committed
55
| `tolerations`            | `[]`           | Toleration labels for pod assignment     |
56
| `unicorn.serviceName`    | `unicorn`      | Unicorn service name                     |
Mike Rennie's avatar
Mike Rennie committed
57

58
## Chart configuration examples
59

60 61
### image.pullSecrets

62 63 64 65 66 67
`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`:
68

69
```yaml
70 71 72 73
image:
  repository: my.shell.repository
  tag: latest
  pullPolicy: Always
74
  pullSecrets:
75 76 77 78
  - name: my-secret-name
  - name: my-secondary-secret-name
```

Mike Rennie's avatar
Mike Rennie committed
79
### tolerations
80

Mike Rennie's avatar
Mike Rennie committed
81 82 83
`tolerations` allow you schedule pods on tainted worker nodes

Below is an example use of `tolerations`:
84 85

```yaml
Mike Rennie's avatar
Mike Rennie committed
86 87 88 89 90 91 92 93 94 95 96
tolerations:
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoExecute"
```

97
### annotations
98

99
`annotations` allows you to add annotations to the GitLab Shell pods.
100 101

Below is an example use of `annotations`
102

103
```yaml
104 105
annotations:
  kubernetes.io/example-annotation: annotation-value
106
```
107

108 109
## External Services

110 111
This chart should be attached the Unicorn service, and should also use the same Redis
as the attached Unicorn service.
112 113 114

### Redis

115
```yaml
116
redis:
117
  host: redis.example.com
118 119
  serviceName: redis
  port: 6379
120 121 122
  sentinels:
    - host: sentinel1.example.com
      port: 26379
123 124 125 126 127
  password:
    secret: gitlab-redis
    key: redis-password
```

128 129 130 131 132 133 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. |

_Note:_ The current Redis Sentinel support only supports Sentinels that have
been deployed separately from the GitLab chart. As a result, the Redis
deployment through the GitLab chart should be disabled with `redis.enabled=false`
and `redis-ha.enabled=false`. The Secret containing the Redis password
will need to be manually created before deploying the GitLab chart.
143 144 145

### Unicorn

146
```yaml
147
unicorn:
148
  host: unicorn.example.com
149
  serviceName: unicorn
150 151 152
  port: 8080
```

153 154 155 156 157
| 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. |
158 159 160 161 162

## Chart Settings

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

163
### hostKeys.secret
164

165 166
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.
167

168
### authToken
169

170 171
GitLab Shell uses an Auth Token in its communication with Unicorn. Share the token
with GitLab Shell and Unicorn using a shared Secret.
172

173
```yaml
174 175 176 177 178
authToken:
 secret: gitlab-shell-secret
 key: secret
```

179 180 181
| Name             | Type    | Default | Description |
|:-----------------|:-------:|:--------|:------------|
| authToken.key    | String  |         | The name of the key in the above secret that contains the authToken. |
182
| authToken.secret | String  |         | The name of the Kubernetes `Secret` to pull from. |
183 184 185 186 187 188 189 190 191 192 193 194

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

195
```yaml
196 197 198 199 200 201 202
service:
  type: LoadBalancer
  loadBalancerIP: 1.2.3.4
  loadBalancerSourceRanges:
  - 5.6.7.8/32
  - 10.0.0.0/8
```