Skip to content

Commit 9628417

Browse files
vasil-cfvasil-cf
committed
fix: README.md
1 parent 0c9d698 commit 9628417

File tree

2 files changed

+206
-55
lines changed

2 files changed

+206
-55
lines changed

‎codefresh/README.md

Lines changed: 103 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ Helm chart for deploying [Codefresh On-Premises](https://codefresh.io/docs/docs/
3434
- [Enable session cookie](#enable-session-cookie)
3535
- [X-Frame-Options response header](#x-frame-options-response-header)
3636
- [Configuring OIDC Provider](#configuring-oidc-provider)
37+
- [Maintaining MongoDB indexes](#maintaining-mongodb-indexes)
3738
- [Upgrading](#upgrading)
3839
- [To 2.0.0](#to-200)
3940
- [To 2.0.12](#to-2012)
@@ -88,7 +89,7 @@ imageCredentials:
8889
password: '{ "type": "service_account", "project_id": "codefresh-enterprise", "private_key_id": ... }'
8990
```
9091
91-
- Specify `.Values.global.appUrl`, `.Values.global.firebaseUrl` and `.Values.global.firebaseSecret`
92+
- Specify `.Values.global.appUrl`, `.Values.global.firebaseUrl`, `.Values.global.firebaseSecret`, `.Values.global.env.MONGOOSE_AUTO_INDEX`, `.Values.global.env.MONGO_AUTOMATIC_INDEX_CREATION`
9293

9394
```yaml
9495
global:
@@ -112,6 +113,14 @@ global:
112113
# firebaseSecretSecretKeyRef:
113114
# name: my-secret
114115
# key: firebase-secret
116+
117+
# -- Enable index creation in MongoDB
118+
# This is required for first-time installations!
119+
# Before usage in Production, you must set it to `false` or remove it!
120+
env:
121+
MONGOOSE_AUTO_INDEX: "true"
122+
MONGO_AUTOMATIC_INDEX_CREATION: "true"
123+
115124
```
116125

117126
- Specify `.Values.ingress.tls.cert` and `.Values.ingress.tls.key` OR `.Values.ingress.tls.existingSecret`
@@ -167,6 +176,17 @@ ingress-nginx:
167176
--timeout 15m
168177
```
169178

179+
### ⚠️ **MANDATORY** Post-Installation Action Items
180+
181+
Once your Codefresh On-Prem instance is installed, configured, and confirmed to be ready for production use, the following variables must be set to `false` or removed:
182+
183+
```yaml
184+
global:
185+
env:
186+
MONGOOSE_AUTO_INDEX: "false"
187+
MONGO_AUTOMATIC_INDEX_CREATION: "false"
188+
```
189+
170190
## Chart Configuration
171191

172192
See [Customizing the Chart Before Installing](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). To see all configurable options with detailed comments, visit the chart's [values.yaml](./values.yaml), or run these configuration commands:
@@ -1391,6 +1411,84 @@ To see all the claims supported by Codefresh OIDC provider, see `claims_supporte
13911411

13921412
Use [obtain-oidc-id-token](https://github.com/codefresh-io/steps/blob/822afc0a9a128384e76459c6573628020a2cf404/incubating/obtain-oidc-id-token/step.yaml#L27-L58) and [aws-sts-assume-role-with-web-identity](https://github.com/codefresh-io/steps/blob/822afc0a9a128384e76459c6573628020a2cf404/incubating/aws-sts-assume-role-with-web-identity/step.yaml#L29-L63) steps to exchange the OIDC token (JWT) for a cloud access token.
13931413

1414+
## Maintaining MongoDB Indexes
1415+
1416+
Sometimes, in new releases of Codefresh On-Prem, index requirements change. When this happens, it's mentioned in the [Upgrading section](#upgrading) for the specific release.
1417+
1418+
> ℹ️ If you're upgrading from version `X` to version `Y`, and index requirements were updated in any of the intermediate versions, you only need to align your indexes with the index requirements of version `Y`. To do that, follow [Index alignment](#index-alignment) instructions.
1419+
1420+
### Index alignment
1421+
1422+
The required index definitions for each release can be found at the following resources:
1423+
1424+
- `2.6` <https://github.com/codefresh-io/codefresh-onprem-helm/tree/release-2.6/indexes>
1425+
1426+
The indexes are stored in JSON files with keys and options specified.
1427+
1428+
The directory structure is:
1429+
1430+
```console
1431+
indexes
1432+
├── <DB_NAME> # MongoDB database name
1433+
│ ├── <COLLECTION_NAME>.json # MongoDB indexes for the specified collection
1434+
```
1435+
1436+
**Overview of the index alignment process:**
1437+
1438+
1. Identify the differences between the indexes in your MongoDB instance and the required index definitions.
1439+
2. Create any missing indexes one by one. (It's important not to create them in bulk.)
1440+
3. Then remove any unnecessary indexes.
1441+
1442+
> ⚠️ **Note! Any changes to indexes should be performed during a defined maintenance window or during periods of lowest traffic to MongoDB.**
1443+
>
1444+
> Building indexes during time periods where the target collection is under heavy write load can result in reduced write performance and longer index builds. ([*Source: MongoDB official documentation*](https://www.mongodb.com/docs/manual/core/index-creation/#index-build-impact-on-database-performance))
1445+
>
1446+
> Even minor changes to indexes (e.g., index removal) can cause brief but noticeable performance degradation ([*Source: MongoDB official documentation*](https://www.mongodb.com/docs/manual/core/query-plans/#plan-cache-flushes))
1447+
1448+
#### Self-hosted MongoDB
1449+
1450+
For self-hosted MongoDB, follow the instructions below:
1451+
1452+
- Connect to the MongoDB server using the [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) shell. Open your terminal or command prompt and run the following command, replacing `<connection_string>` with the appropriate MongoDB connection string for your server:
1453+
1454+
```shell
1455+
mongosh "<connection_string>"
1456+
```
1457+
1458+
- Retrieve the list of indexes for a specific collection:
1459+
1460+
```js
1461+
db.getSiblingDB('<db_name>').getCollection('<collection_name>').getIndexes()
1462+
```
1463+
1464+
- Compare your indexes with the required indexes for the target release, and adjust them by creating any missing indexes or removing any unnecessary ones
1465+
1466+
**Index creation**
1467+
1468+
> ⚠ **Note! Always create indexes sequentially, one by one. Don't create them in bulk.**
1469+
1470+
- To create an index, use the `createIndex()` method:
1471+
1472+
```js
1473+
db.getSiblingDB('<db_name>').getCollection('<collection_name>').createIndex(<keys_object>, <options_object>)
1474+
```
1475+
1476+
After executing the `createIndex()` command, you should see a result indicating that the index was created successfully.
1477+
1478+
**Index removal**
1479+
1480+
- To remove an index, use the `dropIndex()` method with either the `<index_name>` or a `<keys_object>`:
1481+
1482+
```js
1483+
db.getSiblingDB('<db_name>').getCollection('<collection_name>').dropIndex('<index_name>' | <keys_object>)
1484+
```
1485+
1486+
#### Atlas Database
1487+
1488+
If you're hosting MongoDB on [Atlas](https://www.mongodb.com/atlas/database), use the following [Manage Indexes](https://www.mongodb.com/docs/atlas/atlas-ui/indexes/) guide to View, Create or Remove indexes.
1489+
1490+
> ⚠️ **Important!** In Atlas in production environment the indexes must be created in *a rolling fashion* mode, i.e., with `Build index via rolling process` checkbox enabled.
1491+
13941492
## Upgrading
13951493

13961494
### To 2.0.0
@@ -1926,6 +2024,10 @@ cfapi:
19262024

19272025
### To 2.6.0
19282026

2027+
> ⚠️ **WARNING! MongoDB indexes changed!**
2028+
>
2029+
> Please, follow [Maintaining MongoDB indexes](#maintaining-mongodb-indexes) guide to meet index requirements **BEFORE** the upgrade process.
2030+
19292031
### [What's new in 2.6.x](https://codefresh.io/docs/docs/whats-new/on-prem-release-notes/#on-premises-version-26)
19302032

19312033
#### Affected values
@@ -1964,32 +2066,6 @@ cfapi:
19642066
digest: ""
19652067
```
19662068

1967-
#### Auto-index creation in MongoDB
1968-
1969-
In Codefresh On-Prem 2.6.x, the `cfapi` can create indexes in MongoDB automatically. This feature is disabled by default. To enable it, set the following environment variable:
1970-
1971-
> **Note!** Enabling this feature can cause performance degradation during the index creation process.
1972-
1973-
> **Note!** It is recommended to add indexes during a maintenance window. The indexes list is provided in `codefresh/files/indexes/<MAJOR.MINOR>/<collection_name>.json` files.
1974-
1975-
```yaml
1976-
cfapi:
1977-
container:
1978-
env:
1979-
MONGOOSE_AUTO_INDEX: "true"
1980-
```
1981-
1982-
```yaml
1983-
argo-platform:
1984-
api-graphql:
1985-
env:
1986-
MONGO_AUTOMATIC_INDEX_CREATION: "true"
1987-
```
1988-
1989-
Ref:
1990-
- [Create an Index in Atlas DB](https://www.mongodb.com/docs/atlas/atlas-ui/indexes/#create-an-index)
1991-
- [Create an Index with mongosh](https://www.mongodb.com/docs/manual/reference/method/db.collection.createIndex/)
1992-
19932069
## Troubleshooting
19942070

19952071
### Error: Failed to validate connection to Docker daemon; caused by Error: certificate has expired

‎codefresh/README.md.gotmpl

Lines changed: 103 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ Helm chart for deploying [Codefresh On-Premises](https://codefresh.io/docs/docs/
3434
- [Enable session cookie](#enable-session-cookie)
3535
- [X-Frame-Options response header](#x-frame-options-response-header)
3636
- [Configuring OIDC Provider](#configuring-oidc-provider)
37+
- [Maintaining MongoDB indexes](#maintaining-mongodb-indexes)
3738
- [Upgrading](#upgrading)
3839
- [To 2.0.0](#to-200)
3940
- [To 2.0.12](#to-2012)
@@ -89,7 +90,7 @@ imageCredentials:
8990
password: '{ "type": "service_account", "project_id": "codefresh-enterprise", "private_key_id": ... }'
9091
```
9192

92-
- Specify `.Values.global.appUrl`, `.Values.global.firebaseUrl` and `.Values.global.firebaseSecret`
93+
- Specify `.Values.global.appUrl`, `.Values.global.firebaseUrl`, `.Values.global.firebaseSecret`, `.Values.global.env.MONGOOSE_AUTO_INDEX`, `.Values.global.env.MONGO_AUTOMATIC_INDEX_CREATION`
9394

9495
```yaml
9596
global:
@@ -113,6 +114,14 @@ global:
113114
# firebaseSecretSecretKeyRef:
114115
# name: my-secret
115116
# key: firebase-secret
117+
118+
# -- Enable index creation in MongoDB
119+
# This is required for first-time installations!
120+
# Before usage in Production, you must set it to `false` or remove it!
121+
env:
122+
MONGOOSE_AUTO_INDEX: "true"
123+
MONGO_AUTOMATIC_INDEX_CREATION: "true"
124+
116125
```
117126

118127
- Specify `.Values.ingress.tls.cert` and `.Values.ingress.tls.key` OR `.Values.ingress.tls.existingSecret`
@@ -168,6 +177,17 @@ ingress-nginx:
168177
--timeout 15m
169178
```
170179

180+
### ⚠️ **MANDATORY** Post-Installation Action Items
181+
182+
Once your Codefresh On-Prem instance is installed, configured, and confirmed to be ready for production use, the following variables must be set to `false` or removed:
183+
184+
```yaml
185+
global:
186+
env:
187+
MONGOOSE_AUTO_INDEX: "false"
188+
MONGO_AUTOMATIC_INDEX_CREATION: "false"
189+
```
190+
171191
## Chart Configuration
172192

173193
See [Customizing the Chart Before Installing](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). To see all configurable options with detailed comments, visit the chart's [values.yaml](./values.yaml), or run these configuration commands:
@@ -1397,6 +1417,84 @@ To see all the claims supported by Codefresh OIDC provider, see `claims_supporte
13971417

13981418
Use [obtain-oidc-id-token](https://github.com/codefresh-io/steps/blob/822afc0a9a128384e76459c6573628020a2cf404/incubating/obtain-oidc-id-token/step.yaml#L27-L58) and [aws-sts-assume-role-with-web-identity](https://github.com/codefresh-io/steps/blob/822afc0a9a128384e76459c6573628020a2cf404/incubating/aws-sts-assume-role-with-web-identity/step.yaml#L29-L63) steps to exchange the OIDC token (JWT) for a cloud access token.
13991419

1420+
## Maintaining MongoDB Indexes
1421+
1422+
Sometimes, in new releases of Codefresh On-Prem, index requirements change. When this happens, it's mentioned in the [Upgrading section](#upgrading) for the specific release.
1423+
1424+
> ℹ️ If you're upgrading from version `X` to version `Y`, and index requirements were updated in any of the intermediate versions, you only need to align your indexes with the index requirements of version `Y`. To do that, follow [Index alignment](#index-alignment) instructions.
1425+
1426+
### Index alignment
1427+
1428+
The required index definitions for each release can be found at the following resources:
1429+
1430+
- `2.6` <https://github.com/codefresh-io/codefresh-onprem-helm/tree/release-2.6/indexes>
1431+
1432+
The indexes are stored in JSON files with keys and options specified.
1433+
1434+
The directory structure is:
1435+
1436+
```console
1437+
indexes
1438+
├── <DB_NAME> # MongoDB database name
1439+
│ ├── <COLLECTION_NAME>.json # MongoDB indexes for the specified collection
1440+
```
1441+
1442+
**Overview of the index alignment process:**
1443+
1444+
1. Identify the differences between the indexes in your MongoDB instance and the required index definitions.
1445+
2. Create any missing indexes one by one. (It's important not to create them in bulk.)
1446+
3. Then remove any unnecessary indexes.
1447+
1448+
> ⚠️ **Note! Any changes to indexes should be performed during a defined maintenance window or during periods of lowest traffic to MongoDB.**
1449+
>
1450+
> Building indexes during time periods where the target collection is under heavy write load can result in reduced write performance and longer index builds. ([*Source: MongoDB official documentation*](https://www.mongodb.com/docs/manual/core/index-creation/#index-build-impact-on-database-performance))
1451+
>
1452+
> Even minor changes to indexes (e.g., index removal) can cause brief but noticeable performance degradation ([*Source: MongoDB official documentation*](https://www.mongodb.com/docs/manual/core/query-plans/#plan-cache-flushes))
1453+
1454+
#### Self-hosted MongoDB
1455+
1456+
For self-hosted MongoDB, follow the instructions below:
1457+
1458+
- Connect to the MongoDB server using the [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) shell. Open your terminal or command prompt and run the following command, replacing `<connection_string>` with the appropriate MongoDB connection string for your server:
1459+
1460+
1461+
```shell
1462+
mongosh "<connection_string>"
1463+
```
1464+
1465+
- Retrieve the list of indexes for a specific collection:
1466+
1467+
```js
1468+
db.getSiblingDB('<db_name>').getCollection('<collection_name>').getIndexes()
1469+
```
1470+
1471+
- Compare your indexes with the required indexes for the target release, and adjust them by creating any missing indexes or removing any unnecessary ones
1472+
1473+
**Index creation**
1474+
1475+
> ⚠ **Note! Always create indexes sequentially, one by one. Don't create them in bulk.**
1476+
1477+
- To create an index, use the `createIndex()` method:
1478+
1479+
```js
1480+
db.getSiblingDB('<db_name>').getCollection('<collection_name>').createIndex(<keys_object>, <options_object>)
1481+
```
1482+
1483+
After executing the `createIndex()` command, you should see a result indicating that the index was created successfully.
1484+
1485+
**Index removal**
1486+
1487+
- To remove an index, use the `dropIndex()` method with either the `<index_name>` or a `<keys_object>`:
1488+
1489+
```js
1490+
db.getSiblingDB('<db_name>').getCollection('<collection_name>').dropIndex('<index_name>' | <keys_object>)
1491+
```
1492+
1493+
#### Atlas Database
1494+
1495+
If you're hosting MongoDB on [Atlas](https://www.mongodb.com/atlas/database), use the following [Manage Indexes](https://www.mongodb.com/docs/atlas/atlas-ui/indexes/) guide to View, Create or Remove indexes.
1496+
1497+
> ⚠️ **Important!** In Atlas in production environment the indexes must be created in *a rolling fashion* mode, i.e., with `Build index via rolling process` checkbox enabled.
14001498

14011499
## Upgrading
14021500

@@ -1934,6 +2032,10 @@ cfapi:
19342032

19352033
### To 2.6.0
19362034

2035+
> ⚠️ **WARNING! MongoDB indexes changed!**
2036+
>
2037+
> Please, follow [Maintaining MongoDB indexes](#maintaining-mongodb-indexes) guide to meet index requirements **BEFORE** the upgrade process.
2038+
19372039
### [What's new in 2.6.x](https://codefresh.io/docs/docs/whats-new/on-prem-release-notes/#on-premises-version-26)
19382040

19392041
#### Affected values
@@ -1972,33 +2074,6 @@ cfapi:
19722074
digest: ""
19732075
```
19742076

1975-
#### Auto-index creation in MongoDB
1976-
1977-
In Codefresh On-Prem 2.6.x, the `cfapi` can create indexes in MongoDB automatically. This feature is disabled by default. To enable it, set the following environment variable:
1978-
1979-
> **Note!** Enabling this feature can cause performance degradation during the index creation process.
1980-
1981-
> **Note!** It is recommended to add indexes during a maintenance window. The indexes list is provided in `codefresh/files/indexes/<MAJOR.MINOR>/<collection_name>.json` files.
1982-
1983-
```yaml
1984-
cfapi:
1985-
container:
1986-
env:
1987-
MONGOOSE_AUTO_INDEX: "true"
1988-
```
1989-
1990-
```yaml
1991-
argo-platform:
1992-
api-graphql:
1993-
env:
1994-
MONGO_AUTOMATIC_INDEX_CREATION: "true"
1995-
```
1996-
1997-
Ref:
1998-
- [Create an Index in Atlas DB](https://www.mongodb.com/docs/atlas/atlas-ui/indexes/#create-an-index)
1999-
- [Create an Index with mongosh](https://www.mongodb.com/docs/manual/reference/method/db.collection.createIndex/)
2000-
2001-
20022077
## Troubleshooting
20032078

20042079
### Error: Failed to validate connection to Docker daemon; caused by Error: certificate has expired

0 commit comments

Comments
 (0)