Skip to content

Commit dc82c14

Browse files
trlytrly
committed
docs: improve private network configuration guide tone and readability
- Revise overview section for clearer explanation of private networks - Enhance certificate management section with step-by-step instructions - Update validation steps with clear expected outcomes
1 parent c21af21 commit dc82c14

File tree

1 file changed

+144
-40
lines changed

1 file changed

+144
-40
lines changed

‎docs/admin/config/private-network.mdx‎

Lines changed: 144 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,30 @@
11
# Private network configuration
22

3-
A **private network** refers to a secure network environment segregated from the public internet, designed to facilitate internal communications and operations within an organization. This network setup restricts external access, enhancing security and control over data flow by limiting exposure to external threats and unauthorized access.
3+
## Overview
4+
A private network is your organization's secure, internal network space - separated from the public internet.
5+
Think of it as your company's own protected environment where internal systems can communicate safely,
6+
keeping your sensitive data and operations shielded from external access.
47

5-
When deploying self-hosted Sourcegraph instances in private networks with specific compliance and policy requirements, additional configuration may be required to ensure all networking features function correctly. The reasons for applying the following configuration options depend on the specific functionality of the Sourcegraph service and the unique network and infrastructure requirements of the organization.
8+
When deploying self-hosted Sourcegraph instances in private networks with specific compliance and policy requirements,
9+
additional configuration may be required to ensure all networking features function correctly. The reasons for applying the following configuration options depend on the specific functionality of the Sourcegraph service and the unique network and infrastructure requirements of the organization.
610

711
The following is a list of Sourcegraph services and how and when each initiates outbound connections to external services:
812

9-
- **executor**: Sourcegraph [Executor](../executors) batch change or precise indexing jobs may need to connect to services hosted within an organization's private network
10-
- **frontend**: The frontend service communicates externally when connecting to external [auth providers](../auth), sending [telemetry data](../pings), testing code host connections, and connecting to [externally hosted](../external_services) Sourcegraph services
13+
- **executor**: Sourcegraph [Executor](../executors) batch change or precise indexing jobs may need to connect to
14+
services hosted within an organization's private network
15+
- **frontend**: The frontend service communicates externally when connecting to external [auth providers](../auth),
16+
sending [telemetry data](../pings), testing code host connections, and connecting to [externally hosted](../external_services) Sourcegraph services
1117
- **gitserver**: Executes git commands against externally hosted [code hosts](../external_service)
1218
- **migrator**: Connects to Postgres instances (which may be [externally hosted](../external_services/postgres)) to process database migrations
1319
- **repo-updater**: Communicates with [code hosts](../external_service) APIs to coordinate repository synchronization
14-
- **worker**: Sourcegraph [Worker](../workers) run various background jobs that may require establishing connections to services hosted within an organization's private network
20+
- **worker**: Sourcegraph [Worker](../workers) run various background jobs that may require establishing connections to
21+
services hosted within an organization's private network
1522

1623
## HTTP proxy configuration
1724

18-
All Sourcegraph services respect the conventional `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for routing Sourcegraph client application HTTP traffic through a proxy server. The steps for configuring proxy environment variables will depend on your Sourcegraph deployment method.
25+
All Sourcegraph services respect the conventional `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for
26+
routing Sourcegraph client application HTTP traffic through a proxy server. The steps for configuring proxy environment
27+
variables will depend on your Sourcegraph deployment method.
1928

2029
### Kubernetes Helm
2130

@@ -32,48 +41,143 @@ executor|frontend|gitserver|migrator|repo-updater|worker:
3241
value: "blobstore,codeinsights-db,codeintel-db,sourcegraph-frontend-internal,sourcegraph-frontend,github-proxy,gitserver,grafana,indexed-search-indexer,indexed-search,jaeger-query,pgsql,precise-code-intel-worker,prometheus,redis-cache,redis-store,repo-updater,searcher,symbols,syntect-server,worker-executors,worker,cloud-sql-proxy,localhost,127.0.0.1,.svc,.svc.cluster.local,kubernetes.default.svc"
3342
```
3443
35-
<Callout type="warning">Failure to configure `NO_PROXY` correctly can cause the proxy configuration to interfere with local networking between internal Sourcegraph services.</Callout>
44+
<Callout type="warning">Failure to configure `NO_PROXY` correctly can cause the proxy configuration to interfere with
45+
local networking between internal Sourcegraph services.</Callout>
3646

37-
## Using private CA root certificates
38-
Some organizations maintain a private Certificate Authority (CA) for issuing certificates within their private network. When Sourcegraph connects to TLS encrypted service using a self-signed certificate that it does not trust, you will observe an `x509: certificate signed by unknown authority` error message in logs.
47+
## Configuring TLS certificates for private networks
3948

40-
In order for Sourcegraph to respect an organization's self-signed certificates, the private CA root certificate(s) will need to be appended to Sourcegraph's trusted CA root certificate list in `/etc/ssl/certs/ca-certificates.crt`.
49+
When deploying Sourcegraph in private networks, you'll often need to configure TLS certificates to establish trusted
50+
connections with internal services like code hosts. The recommended approach is to configure root CA certificates
51+
through Sourcegraph's site configuration using `tls.external` in the `experimentalFeatures` section.
4152

42-
### Configuring sourcegraph-frontend to recognize private CA root certificates
43-
The following details the process for setting up the sourcegraph-frontend to acknowledge and trust a private CA root certificate for Sourcegraph instances deployed using [Helm](../deploy/kubernetes/helm). For any other Sourcegraph service that needs to trust an organization's private CA root certificate (including gitserver, repo-updater, or migrator), similar steps will need to be followed.
53+
This method offers several advantages:
54+
- Works consistently across both Cloud and self-hosted deployments
55+
- Requires minimal configuration changes
56+
- Can be managed entirely through the web UI
57+
- Maintains certificates in a centralized location
58+
- Aligns with enterprise PKI best practices
4459

45-
1. Copy out the existing `ca-certificates.crt` file from the sourcegraph-frontend container:
46-
```sh
47-
kubectl cp $(kubectl get pod -l app=sourcegraph-frontend -o jsonpath='{.items[0].metadata.name}'):/etc/ssl/certs/ca-certificates.crt sourcegraph-frontend-ca-certificates.crt
48-
```
49-
2. Concatenate the private CA root certificate to the `sourcegraph-frontend-ca-certificates.crt` file:
50-
```sh
51-
cat sourcegraph-frontend-ca-certificates.crt {private-ca-certificate.crt file} > ca-certificates.crt
52-
```
53-
3. Create a new Kubernetes ConfigMap containing the concatenated `ca-certificates.crt` file:
54-
```sh
55-
kubectl create configmap sourcegraph-frontend-ca-certificates --from-file=ca-certificates.crt
60+
The configuration process involves identifying and adding the public key of your organization's root Certificate
61+
Authority (CA) to Sourcegraph's site configuration. This approach is particularly efficient because:
62+
* Root CA certificates typically have long expiration periods (often measured in years)
63+
* A single root CA certificate usually covers multiple internal services
64+
* The configuration can be managed without container modifications or filesystem changes
65+
66+
### Obtain the certificate chain
67+
Use the OpenSSL command to extract the certificate chain from your code host.
68+
Replace the domain and port with your internal code host's values:
69+
70+
```bash
71+
openssl s_client -showcerts -connect github.com:443 \
72+
-nameopt lname < /dev/null > certs.log 2>&1
5673
```
57-
4. Mount the `sourcegraph-frontend-ca-certificates` ConfigMap to the sourcegraph-frontend Deployment:
58-
```yaml
59-
frontend:
60-
extraVolumes:
61-
- name: ca-certificates
62-
configMap:
63-
name: sourcegraph-frontend-ca-certificates
64-
extraVolumeMounts:
65-
- name: ca-certificates
66-
mountPath: /etc/ssl/certs/
74+
75+
### Identify the root certificate
76+
In the generated `certs.log` file, locate the root CA certificate:
77+
78+
Certificate chains typically include 3 certificates:
79+
80+
* Root certificate authority (depth=3).
81+
* Intermediate certificate authority (depth=1).
82+
* Server (leaf) certificate (depth=0).
83+
84+
The certificate with the highest depth number in the chain will be the root CA certificate.
85+
86+
The root CA certificate will typically have:
87+
88+
* A long expiration period (years).
89+
* A descriptive common name (e.g., "Enterprise Root CA 2023").
90+
91+
Example root CA certificate for github.com:
92+
93+
```text
94+
Connecting to 140.82.114.3
95+
depth=2 countryName=US, stateOrProvinceName=New Jersey, localityName=Jersey City, organizationName=The USERTRUST Network, commonName=USERTrust ECC Certification Authority
96+
verify return:1
97+
depth=1 countryName=GB, stateOrProvinceName=Greater Manchester, localityName=Salford, organizationName=Sectigo Limited, commonName=Sectigo ECC Domain Validation Secure Server CA
98+
verify return:1
99+
depth=0 commonName=github.com
100+
verify return:1
101+
CONNECTED(00000005)
102+
---
103+
...
104+
2 s:countryName=US, stateOrProvinceName=New Jersey, localityName=Jersey City, organizationName=The USERTRUST Network, commonName=USERTrust ECC Certification Authority
105+
i:countryName=GB, stateOrProvinceName=Greater Manchester, localityName=Salford, organizationName=Comodo CA Limited, commonName=AAA Certificate Services
106+
a:PKEY: id-ecPublicKey, 384 (bit); sigalg: RSA-SHA384
107+
v:NotBefore: Mar 12 00:00:00 2019 GMT; NotAfter: Dec 31 23:59:59 2028 GMT
108+
-----BEGIN CERTIFICATE-----
109+
MII...c=
110+
-----END CERTIFICATE-----
67111
```
68112

69-
Once deployed, you should see the private CA root certificate in the sourcegraph-frontend container's `/etc/ssl/certs/ca-certificates.crt` file.
70-
```sh
71-
kubectl exec -it $(kubectl get pod -l app=sourcegraph-frontend -o jsonpath='{.items[0].metadata.name}') -- tail /etc/ssl/certs/ca-certificates.crt
113+
### Format the certificate
114+
Once you've identified the root CA certificate:
115+
116+
* Extract the certificate content including the BEGIN and END markers.
117+
* Format the certificate for the site configuration:
118+
* Replace newlines with \n characters.
119+
* Enclose the entire certificate in double quotes.
120+
* Add a trailing comma.
121+
122+
### Add the certificate to the site configuration
123+
124+
Add the formatted certificate to your Sourcegraph site configuration.
125+
126+
```json
127+
{
128+
"experimentalFeatures": {
129+
"tls.external": {
130+
"certificates": [
131+
"-----BEGIN CERTIFICATE-----\naZ...==\n-----END CERTIFICATE-----"
132+
]
133+
}
134+
}
135+
}
72136
```
73137

74-
You can verify that the self-signed certificate is trusted using `curl`:
75-
```sh
76-
kubectl exec -it $(kubectl get pod -l app=sourcegraph-frontend -o jsonpath='{.items[0].metadata.name}') -- curl -v {https://internal.service.example.com} > /dev/null
138+
For organizations with multiple root CAs (uncommon), additional certificates can be added to the array:
139+
```json
140+
{
141+
"experimentalFeatures": {
142+
"tls.external": {
143+
"certificates": [
144+
"-----BEGIN CERTIFICATE-----\naZ...==\n-----END CERTIFICATE-----",
145+
"-----BEGIN CERTIFICATE-----\nMI...I7\n-----END CERTIFICATE-----"
146+
]
147+
}
148+
}
149+
}
77150
```
78151

79-
<Callout type="note">It is recommended to repeat these steps on a regular cadence to ensure that Sourcegraph's CA root certificate list stays up to date.</Callout>
152+
### Validation of certificate configuration
153+
These steps confirms that configuring the root CA certificate through `tls.external` is sufficient for all standard
154+
Sourcegraph operations that require secure connections to internal services.
155+
156+
1. **Code host connectivity**
157+
- Verify using the UI "Test Connection" button
158+
- Trigger validate completed sync jobs
159+
<Callout type="info">Executed by: sourcegraph-frontend service</Callout>
160+
161+
2. **Repository operations**
162+
- Verify individual repository synchronization
163+
- Verify cloning operations
164+
<Callout type="info">Executed by: gitserver service</Callout>
165+
166+
3. **Permission synchronization**
167+
- Verify user-centric permission sync jobs
168+
<Callout type="info">Executed by: worker service</Callout>
169+
170+
<Callout type="note">
171+
Repository-centric permission sync jobs are expected to behave identically, as they use the same underlying TLS configuration mechanisms.
172+
</Callout>
173+
174+
### Recommended best practices
175+
* Only include root CA certificates, not intermediate or server certificates.
176+
* Avoid using insecureSkipVerify: true and add TLS certificates if needed, as it bypasses important security checks.
177+
* Document certificate sources and expiration dates in your organization's runbooks.
178+
* Plan for certificate rotation well before root CA expiration.
179+
* Most enterprises use a single root CA, so adding one certificate often covers all internal services.
180+
* Keep the certificate list minimal and well-maintained.
181+
182+
183+

0 commit comments

Comments
 (0)