Skip to content

Commit 8e02f9a

Browse files
josh-wongjosh-wong
committed
AUTO: Sync Helm Charts docs to ScalarDL docs site repo
1 parent a8a2047 commit 8e02f9a

File tree

2 files changed

+164
-138
lines changed

2 files changed

+164
-138
lines changed

‎versioned_docs/version-3.9/helm-charts/configure-custom-values-scalar-manager.mdx

Lines changed: 86 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -4,32 +4,34 @@ tags:
44
displayed_sidebar: docsEnglish
55
---
66

7-
# Configure a custom values file for Scalar Manager
7+
# Configure a Custom Values File for Scalar Manager
88

9-
This document explains how to create your custom values file for the Scalar Manager chart. If you want to know the details of the parameters, please refer to the [README](https://github.com/scalar-labs/helm-charts/blob/main/charts/scalar-manager/README.md) of the Scalar Manager chart.
9+
This document provides instructions on how to configure a custom values file for the Scalar Manager Helm Chart. For details about the available parameters, see the [README](https://github.com/scalar-labs/helm-charts/blob/main/charts/scalar-manager/README.md) in the Scalar Manager chart repository.
1010

1111
## Required configurations
1212

13+
This section describes the service, image, and Scalar Manager configurations that you must include in the Scalar Manager values file.
14+
1315
### Service configurations
1416

15-
You must set `service.type` to specify the Service resource type of Kubernetes. If you want to use a load balancer provided by could providers, you need to set `service.type` to `LoadBalancer`.
17+
You must configure `web.service.type` to define the Kubernetes Service resource type. To use a load balancer that cloud service providers offer for exposing the service, set `web.service.type` to `LoadBalancer`.
1618

1719
```yaml
18-
service:
19-
type: LoadBalancer
20+
web:
21+
service:
22+
type: LoadBalancer
23+
# other web configurations
2024
```
2125

22-
#### Security concerns regarding exposing Scalar Manager
26+
#### Security considerations for exposing Scalar Manager
2327

24-
Setting `service.type` to `LoadBalancer` exposes Scalar Manager outside the cluster, which may be a security concern.
28+
Setting `web.service.type` to `LoadBalancer` exposes Scalar Manager externally via `HTTP` by default, which creates security risks on untrusted networks due to unencrypted traffic. If external access is not required, using a private network or properly configuring network access to your Kubernetes cluster is recommended.
2529

26-
Currently, Scalar Manager lacks authentication or access-control mechanisms. Because of this, exposing Scalar Manager directly to a public network without proper security measures can lead to unauthorized actions, because Scalar Manager provides features like scheduling jobs to pause Scalar products.
30+
Scalar Manager supports authentication and authorization mechanisms. You can configure these mechanisms to ensure authorized actions for features like scheduling jobs to pause Scalar products. For details, see [Authentication configuration for Scalar Manager](#authentication-configuration-for-scalar-manager).
2731

28-
If external access is necessary, using a private network or properly configuring network access to your Kubernetes cluster is recommended.
32+
### Container image configurations
2933

30-
### Image configurations
31-
32-
You must set `api.image.repository` and `web.image.repository`. Be sure to specify the Scalar Manager container image so that you can pull the image from the container repository.
34+
You must configure `api.image.repository` and `web.image.repository`. These settings specify the Scalar Manager container images, ensuring you can pull them from the container repository.
3335

3436
```yaml
3537
api:
@@ -42,86 +44,106 @@ web:
4244
4345
## Optional configurations
4446
45-
This section explains the optional configurations when setting up a custom values file for Scalar Manager.
47+
This section describes optional configurations for customizing the Scalar Manager values file.
4648
4749
### Scalar Manager configurations (optional based on your environment)
4850
49-
You can override the `api.applicationProperties` custom value to change the default configurations of Scalar Manager.
51+
You can override the `api.applicationProperties` setting to modify the default Scalar Manager configurations.
5052

5153
```yaml
5254
api:
5355
applicationProperties: |
54-
grafana.kubernetesServiceLabelName="app.kubernetes.io/name"
55-
grafana.kubernetesServiceLabelValue="grafana"
56-
grafana.kubernetesServicePortName="http-web"
56+
prometheus.kubernetes-service-label-name="app"
57+
prometheus.kubernetes-service-label-value="kube-prometheus-stack-prometheus"
58+
prometheus.kubernetes-service-port-name="http-web"
59+
# other application properties
5760
```
5861

59-
Scalar Manager has default configurations that, for example, discover Scalar product deployments and the Prometheus and Loki services in the cluster. In most use cases, especially if you follow the [guide to deploy `kube-prometheus-stack`](getting-started-monitoring.mdx) and the [guide to deploy `loki-stack`](getting-started-logging.mdx), you don't need to change the default configurations.
62+
Scalar Manager includes default configurations to discover Scalar product deployments and the Prometheus service within the cluster. In most scenarios, especially when following the guides to deploy `kube-prometheus-stack` and `loki-stack`, these default configurations are sufficient and do not require modification.
6063

61-
#### Properties that you can set in `api.applicationProperties`
64+
#### Configurable properties in `api.applicationProperties`
6265

6366
The configurations for Scalar Manager are in the format of Java application properties, which are `key=value` pairs. These application properties can be set by using the `api.applicationProperties` custom value in the Scalar Manager Helm Chart.
6467

65-
|Name|Description|Default value|
66-
|---|---|---|
67-
|`grafana.kubernetesServiceLabelName`|The label name used to discover the Grafana service in Kubernetes|`app.kubernetes.io/name`|
68-
|`grafana.kubernetesServiceLabelValue`|The label value corresponding to `grafana.kubernetesServiceLabelName`|`grafana`|
69-
|`grafana.kubernetesServicePortName`|The port name used to discover the Grafana service port in Kubernetes|`http-web`|
70-
|`prometheus.kubernetesServiceLabelName`|The label name used to discover the Prometheus service in Kubernetes|`app`|
71-
|`prometheus.kubernetesServiceLabelValue`|The label value corresponding to `prometheus.kubernetesServiceLabelName`|`kube-prometheus-stack-prometheus`|
72-
|`prometheus.kubernetesServicePortName`|The port name used to discover the Prometheus service port in Kubernetes|`http-web`|
73-
|`loki.kubernetesServiceLabelName`|The label name used to discover the Loki service in Kubernetes|`app`|
74-
|`loki.kubernetesServiceLabelValue`|The label value corresponding to `loki.kubernetesServiceLabelName`|`loki`|
75-
|`loki.kubernetesServicePortName`|The port name used to discover the Loki service port in Kubernetes|`http-metrics`|
76-
|`helm.scalarRepositoryName`|The name used to represent the Scalar Helm repository|`scalar-labs`|
77-
|`helm.scalarRepositoryUrl`|The URL of the Scalar Helm repository|`https://scalar-labs.github.io/helm-charts`|
78-
|`helm.scalarAdminForKubernetesChartName`|The Helm Chart name of `Scalar Admin for Kubernetes` in the Scalar Helm repository|`scalar-admin-for-kubernetes`|
79-
|`helm.scalarAdminForKubernetesChartVersion`|The version of the Scalar Admin for Kubernetes Helm Chart|`1.0.0`|
80-
|`configMapNamespace`|The namespace where the ConfigMap used by Scalar Manager is deployed|`default`|
81-
|`configMapName`|The name of the ConfigMap used by Scalar Manager|`scalar-manager-metadata`|
82-
|`paused-state-retention.storage`|The storage type used to retain paused states|`configmap`|
83-
|`paused-state-retention.max-number`|The max number that the paused states are retained by Scalar Manager|`100`|
68+
| Name | Description | Default Value |
69+
|:--------------------------------------------------------------------|:----------------------------------------------------------------------------|:---------------------------------------------------------------------------|
70+
| `prometheus.kubernetes-service-label-name` | The label name used to discover the Prometheus service in Kubernetes | `app` |
71+
| `prometheus.kubernetes-service-label-value` | The label value corresponding to `prometheus.kubernetes-service-label-name` | `kube-prometheus-stack-prometheus` |
72+
| `prometheus.kubernetes-service-port-name` | The port name used to discover the Prometheus service port in Kubernetes | `http-web` |
73+
| `springdoc.swagger-ui.enabled` | Whether to enable the Swagger UI or not | `false` |
74+
| `springdoc.swagger-ui.path` | The path of the Swagger UI | `/swagger-ui.html` |
75+
| `app.cors.allowed-origins` | The allowed origins for CORS | `*` |
76+
| `app.cors.allowed-methods` | The allowed methods for CORS | `*` |
77+
| `app.cors.allowed-headers` | The allowed headers for CORS | `*` |
78+
| `authentication.providers.static-jwt.secret` | Secret key used for signing JWT tokens; minimum 32 characters | `example-jwt-secret-with-minimum-32-characters` |
79+
| `authentication.providers.static-jwt.issuer-uri` | The issuer URI of the JWT tokens | `https://scalar-manager.example.com` |
80+
| `authentication.providers.static-jwt.access-token-expiration-time` | The expiration time of the access token | `1h` |
81+
| `authentication.providers.static-jwt.refresh-token-expiration-time` | The expiration time of the refresh token | `3d` |
82+
| `app.initial-admin-user.enabled` | Whether to enable the initial admin user or not | `true` |
83+
| `app.initial-admin-user.email` | The email address of the initial admin user | `[email protected]` |
84+
| `app.initial-admin-user.name` | The name of the initial admin user | `Administrator` |
85+
| `app.initial-admin-user.password` | The password of the initial admin user | `Password@123!` |
86+
| `spring.jpa.hibernate.ddl-auto` | The DDL mode for Hibernate | `update` |
87+
| `spring.jpa.show-sql` | Whether to show the SQL query | `false` |
88+
| `spring.jpa.properties.hibernate.format_sql` | Whether to format the SQL query | `false` |
89+
| `spring.datasource.url` | The URL of the database | `jdbc:postgresql://scalar-manager-postgres-postgresql:5432/scalar-manager` |
90+
| `spring.datasource.username` | The username of the database | `scalar-manager` |
91+
| `spring.datasource.password` | The password of the database | `scalar-manager` |
92+
| `spring.datasource.driver-class-name` | The driver class name of the database | `org.postgresql.Driver` |
8493

85-
##### Service discovery
94+
:::note
8695

87-
Scalar Manager uses label selectors to discover Grafana, Prometheus, and Loki services in Kubernetes, and then uses the port name to connect to them. You can modify the label selectors and the port name by setting the `*.kubernetesServiceLabelName`, `*.kubernetesServiceLabelValue`, and `*.kubernetesServicePortName` configurations.
96+
There are more configurations that you can set in `api.applicationProperties` regarding the JPA, Hibernate, and Spring Data. If you're familiar with these configurations, you can set them to customize the database connection and the behavior of Scalar Manager.
8897

89-
In general, you don't need to modify these configurations. However, if you customized the labels or port names of the Grafana, Prometheus, or Loki services when installing their Helm Charts, you should adjust these configurations to match your customizations.
98+
:::
9099

91-
##### Use of Scalar Admin for Kubernetes
100+
##### Authentication configuration for Scalar Manager
92101

93-
Scalar Manager installs the [Scalar Admin for Kubernetes](https://github.com/scalar-labs/scalar-admin-for-kubernetes) Helm Chart to schedule or execute the pausing of jobs on Scalar products. It sets up the Scalar Helm repository and locates the Helm Chart by using the following configurations:
102+
By default, to access Scalar Manager, you need to authenticate by using a username and password.
94103

95-
- `helm.scalarRepositoryName`
96-
- `helm.scalarRepositoryUrl`
97-
- `helm.scalarAdminForKubernetesChartName`
98-
- `helm.scalarAdminForKubernetesChartVersion`
104+
The following are the prerequisites for setting up authentication:
99105

100-
:::note
106+
- You need to have a PostgreSQL database, either your own or one that a cloud service provider hosts. For example, you can use the [Bitnami package for PostgreSQL](https://artifacthub.io/packages/helm/bitnami/postgresql) to deploy a PostgreSQL database in your Kubernetes cluster.
107+
- You must set the `authentication.providers.static-jwt.secret` configuration. This configuration is used for signing JWT tokens, and the minimum length of the secret is 32 characters.
101108

102-
Modifying these configurations isn't recommended unless you have a specific reason to do so.
109+
The following is an example of the additional configurations you need to set in the `api.applicationProperties` to apply the above prerequisites. Be sure to change the configurations to match your environment.
103110

104-
:::
111+
```properties
112+
# JWT configuration
113+
# Secret key used for signing JWT tokens, minimum 32 characters
114+
authentication.providers.static-jwt.secret=${AUTHENTICATION_PROVIDERS_STATIC_JWT_SECRET:example-jwt-secret-with-minimum-32-characters}
115+
authentication.providers.static-jwt.issuer-uri=${AUTHENTICATION_PROVIDERS_STATIC_JWT_ISSUER_URI:https://scalar-manager.example.com}
116+
authentication.providers.static-jwt.access-token-expiration-time=${AUTHENTICATION_PROVIDERS_STATIC_JWT_ACCESS_TOKEN_EXPIRATION_TIME:1h}
117+
authentication.providers.static-jwt.refresh-token-expiration-time=${AUTHENTICATION_PROVIDERS_STATIC_JWT_REFRESH_TOKEN_EXPIRATION_TIME:3d}
105118
106-
##### ConfigMap used by Scalar Manager
119+
# Initial admin configuration
120+
app.initial-admin-user.enabled=${APP_INITIAL_ADMIN_USER_ENABLED:true}
121+
app.initial-admin-user.email=${APP_INITIAL_ADMIN_USER_EMAIL:[email protected]}
122+
app.initial-admin-user.name=${APP_INITIAL_ADMIN_USER_NAME:Administrator}
123+
app.initial-admin-user.password=${APP_INITIAL_ADMIN_USER_PASSWORD:Password@123!}
107124
108-
Scalar Manager uses ConfigMap to store metadata, such as the default application properties. ConfigMap is deployed in the namespace specified by the following configurations:
125+
# JPA configuration
126+
spring.jpa.hibernate.ddl-auto=${SPRING_JPA_HIBERNATE_DDL_AUTO:update}
127+
spring.jpa.show-sql=${SPRING_JPA_SHOW_SQL:false}
128+
spring.jpa.properties.hibernate.format_sql=${SPRING_JPA_PROPERTIES_HIBERNATE_FORMAT_SQL:false}
109129
110-
- `configMapNamespace`
111-
- `configMapName`
112-
113-
:::note
114-
115-
Modifying these configurations isn't recommended unless you have a specific reason to do so, like if you're using a conflicting ConfigMap.
130+
# Database configuration
131+
spring.datasource.url=jdbc:postgresql://${DATABASE_HOST:scalar-manager-postgres-postgresql}:${DATABASE_PORT:5432}/${DATABASE_NAME:scalar-manager}
132+
spring.datasource.username=${DATABASE_USERNAME:scalar-manager}
133+
spring.datasource.password=${DATABASE_PASSWORD:scalar-manager}
134+
spring.datasource.driver-class-name=org.postgresql.Driver
135+
```
116136

117-
:::
137+
##### Service discovery
118138

119-
##### Retention of paused states
139+
Scalar Manager uses labels to discover the Prometheus service in Kubernetes, and then uses the port name to connect to them. You can modify the labels and the port name by setting the `prometheus.kubernetes-service-label-name`, `prometheus.kubernetes-service-label-value`, and `prometheus.kubernetes-service-port-name` configurations.
120140

121-
Scalar Manager retains the paused states of Scalar products in storage. Currently, Scalar Manager can only use ConfigMap as the storage, so the `paused-state-retention.storage` configuration must be set to `configmap`. You can adjust the maximum number of paused states that Scalar Manager retains by setting the `paused-state-retention.max-number` configuration.
141+
In general, you don't need to modify these configurations. However, if you customized the labels or port names of the Prometheus service when installing their Helm Charts, you should adjust these configurations to match your customizations.
122142

123-
:::warning
143+
#### Configurable environment variables in `web.env`
124144

125-
When using ConfigMap for storage, it is not recommended to set a large value for `paused-state-retention.max-number` due to the size limitation of ConfigMap. Data stored in a ConfigMap cannot exceed 1 MiB, which means that the maximum number of paused states that Scalar Manager can retain is approximately 3,000.
145+
| Name | Description | Default Value |
146+
|:---------------------|:---------------------------------------------------------|:---------------------------------------------------------------------|
147+
| `GRAFANA_SERVER_URL` | The URL of the Grafana service in the Kubernetes cluster | `http://scalar-monitoring-grafana.monitoring.svc.cluster.local:3000` |
126148

127-
:::
149+
Currently, the `GRAFANA_SERVER_URL` variable can be set in `web.env` to customize the proxy from the Scalar Manager web UI to the Grafana UI. By default, the variable is set to the Grafana service `scalar-monitoring-grafana` installed in the `monitoring` namespace. If you have installed Grafana in different namespace or have changed the name of the Grafana service, you will need to update the `GRAFANA_SERVER_URL` variable accordingly.

0 commit comments

Comments
 (0)