# x-onyxia
Onyxia defines a custom extension to the [JSON Schema spec](/docs.onyxia.sh/v11/admin-doc/catalog-of-services/custom-catalogs/json-schema-support.md). It adds Onyxia-specific properties under a reserved key: `x-onyxia`.
The main use case is per-user defaults based on identity. For example, you can inject the right Git and S3 credentials for each user.
### overwriteDefaultWith
Let's consider a sample of the `values.schema.json` of the InseeFrLab/helm-charts-interactive-services' Jupyter chart:
And it translates into this:
{% embed url="" %}
Note the `"git.name"`, `"git.email"` and `"git.token"`, this enables [onyxia-web](https://github.com/InseeFrLab/onyxia-web) to pre fill the fields.
If the user took the time to fill its profile information, [onyxia-web](https://github.com/InseeFrLab/onyxia-web) knows what is the Git **username**, **email** and **personal access token** of the user.
[Here](https://github.com/InseeFrLab/onyxia/blob/main/web/src/core/ports/OnyxiaApi/XOnyxia.ts) is defined the structure of the context that you can use in the `overwriteDefaultWith` field:
```typescript
export type XOnyxiaParams = {
/**
* This is where you can reference values from the onyxia context so that they
* are dynamically injected by the Onyxia launcher.
*
* Examples:
* "overwriteDefaultWith": "user.email" ( You can also write "{{user.email}}" it's equivalent )
* "overwriteDefaultWith": "{{project.id}}-{{k8s.randomSubdomain}}.{{k8s.domain}}"
* "overwriteDefaultWith": [ "a hardcoded value", "some other hardcoded value", "{{region.oauth2.clientId}}" ]
* "overwriteDefaultWith": { "foo": "bar", "bar": "{{region.oauth2.clientId}}" }
*
*/
overwriteDefaultWith?:
| string
| number
| boolean
| unknown[]
| Record;
overwriteListEnumWith?: unknown[] | string;
hidden?: boolean;
readonly?: boolean;
useRegionSliderConfig?: string;
};
export type XOnyxiaContext = {
user: {
idep: string;
name: string;
email: string;
password: string;
ip: string;
darkMode: boolean;
lang: "en" | "fr" | "zh-CN" | "no" | "fi" | "nl" | "it" | "es" | "de";
/**
* Decoded JWT OIDC ID token of the user launching the service.
*
* Sample value:
* {
* "sub": "9000ffa3-5fb8-45b5-88e4-e2e869ba3cfa",
* "name": "Joseph Garrone",
* "aud": ["onyxia", "minio-datanode"],
* "groups": [
* "USER_ONYXIA",
* "codegouv",
* "onyxia",
* "sspcloud-admin",
* ],
* "preferred_username": "jgarrone",
* "given_name": "Joseph",
* "locale": "en",
* "family_name": "Garrone",
* "email": "joseph.garrone@insee.fr",
* "policy": "stsonly",
* "typ": "ID",
* "azp": "onyxia",
* "email_verified": true,
* "realm_access": {
* "roles": ["offline_access", "uma_authorization", "default-roles-sspcloud"]
* }
* }
*/
decodedIdToken: Record;
accessToken: string;
refreshToken: string;
// See: https://docs.onyxia.sh/v/v10/admin-doc/catalog-of-services/customize-your-charts/declarative-user-profile
profile: Record | undefined;
};
service: {
oneTimePassword: string;
};
project: {
id: string;
password: string;
basic: string;
};
git: {
name: string;
email: string;
credentials_cache_duration: number;
token: string | undefined;
};
vault: {
VAULT_ADDR: string;
VAULT_TOKEN: string;
VAULT_MOUNT: string;
VAULT_TOP_DIR: string;
};
s3: {
AWS_ACCESS_KEY_ID: string;
AWS_SECRET_ACCESS_KEY: string;
AWS_SESSION_TOKEN: string;
AWS_DEFAULT_REGION: string;
AWS_S3_ENDPOINT: string;
AWS_BUCKET_NAME: string;
port: number;
pathStyleAccess: boolean;
/**
* The user is assumed to have read/write access on every
* object starting with this prefix on the bucket
**/
objectNamePrefix: string;
/**
* Only for making it easier for charts editors.
* /
* */
workingDirectoryPath: string;
/**
* If true the bucket's (directory) should be accessible without any credentials.
* In this case s3.AWS_ACCESS_KEY_ID, s3.AWS_SECRET_ACCESS_KEY and s3.AWS_SESSION_TOKEN
* will be empty strings.
*/
isAnonymous: boolean;
};
region: {
defaultIpProtection: boolean | undefined;
defaultNetworkPolicy: boolean | undefined;
allowedURIPattern: string;
customValues: Record | undefined;
kafka:
| {
url: string;
topicName: string;
}
| undefined;
tolerations: unknown[] | undefined;
from: unknown[] | undefined;
nodeSelector: Record | undefined;
startupProbe: Record | undefined;
sliders: Record<
string,
{
sliderMin: number;
sliderMax: number;
sliderStep: number;
sliderUnit: string;
}
>;
resources:
| {
cpuRequest?: `${number}${string}`;
cpuLimit?: `${number}${string}`;
memoryRequest?: `${number}${string}`;
memoryLimit?: `${number}${string}`;
disk?: `${number}${string}`;
gpu?: `${number}`;
}
| undefined;
};
k8s: {
domain: string;
ingressClassName: string | undefined;
ingress: boolean | undefined;
route: boolean | undefined;
istio:
| {
enabled: boolean;
gateways: string[];
}
| undefined;
randomSubdomain: string;
initScriptUrl: string;
useCertManager: boolean;
certManagerClusterIssuer: string | undefined;
};
proxyInjection:
| {
enabled: string | undefined;
httpProxyUrl: string | undefined;
httpsProxyUrl: string | undefined;
noProxy: string | undefined;
}
| undefined;
packageRepositoryInjection:
| {
cranProxyUrl: string | undefined;
condaProxyUrl: string | undefined;
packageManagerUrl: string | undefined;
pypiProxyUrl: string | undefined;
}
| undefined;
certificateAuthorityInjection:
| {
cacerts: string | undefined;
pathToCaBundle: string | undefined;
}
| undefined;
};
```
You can also concatenate string values using by wrapping the XOnyxia targeted values in `{{}}`.
{% code title="values.shema.json" %}
```json
"hostname": {
"type": "string",
"form": true,
"title": "Hostname",
"x-onyxia": {
"overwriteDefaultWith": "{{project.id}}-{{k8s.randomSubdomain}}.{{k8s.domain}}"
}
}
```
{% endcode %}
### overwriteListEnumWith
This is an option for customizing the options of the forms fields rendered as select.
Example of select form field in the onyxia launcher
In your values shema such a field would be defined like:
{% code title="values.shema.json" %}
```json
"pullPolicy": {
"type": "string",
"default": "IfNotPresent",
"listEnum": [
"IfNotPresent",
"Always",
"Never"
]
}
```
{% endcode %}
But what if you want to dynamically generate the option? For this you can use the overwriteListEnumWith x-onyxia option.\
For example if you need to let the user select one of the groups he belongs to you can write:
### overwriteSchemaWith
See: [values.schema.json overrides](/docs.onyxia.sh/v11/admin-doc/catalog-of-services/override-schema-for-a-specific-instance.md)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onyxia.sh/docs.onyxia.sh/v11/admin-doc/catalog-of-services/custom-catalogs/onyxia-extension.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.