Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update kratos doc #514

Merged
merged 4 commits into from
Oct 6, 2022
Merged

docs: update kratos doc #514

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b1eb5d3
update kratos doc
Sep 22, 2022
3354d91
remove the other configs under automigration
Sep 23, 2022
294e9e4
automigrate config is renamed
Sep 28, 2022
2f14b71
update doc on passing schema in file
Oct 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
90 changes: 73 additions & 17 deletions docs/helm/kratos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ To install Ory Kratos, the following values must be set

- `kratos.config.secrets.default`
- `kratos.config.dsn`
- `kratos.config.selfservice.default_browser_return_url`
- `kratos.config.courier.smtp.connection_uri`
- `kratos.config.identity.schemas`


You can create a `values.yaml` file to set the required values, like so:

Expand All @@ -27,6 +31,59 @@ kratos:
default:
- dolore occaecat nostrud Ut
- sit et commodoaute ut voluptate consectetur Duis
identity:
default_schema_id: default
schemas:
- id: default
url: file:///etc/config/identity.default.schema.json
courier:
smtp:
connection_uri: smtps://test:test@mailslurper:1025/?skip_ssl_verify=true
selfservice:
default_browser_return_url: http://127.0.0.1:4455/
automigration:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automigration is set to job by default, if we want to specify here which values have to be enabled, the we can shorten that to:

automigration:
  enabled: true

However, this doesn't have to be enabled, as you can and sometimes might want to run the migrations manually

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's worth setting it to true to provide an example that would work without modification. Or else user would likely see database error in pod.
I would remove the other configs under automigration.

enabled: true
type: job
customCommand: []
customArgs: []
identitySchemas:
'identity.default.schema.json': |
{
"$id": "https://schemas.ory.sh/presets/kratos/identity.email.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Person",
"type": "object",
"properties": {
"traits": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"title": "E-Mail",
"ory.sh/kratos": {
"credentials": {
"password": {
"identifier": true
}
},
"recovery": {
"via": "email"
},
"verification": {
"via": "email"
}
}
}
},
"required": [
"email"
],
"additionalProperties": false
}
}
}

```

Install Ory Kratos by running this command:
Expand Down Expand Up @@ -102,37 +159,36 @@ secret:

### Identity Schemas

There are two options to provide identity schemas as file (consider, Kratos
expects `user.schema.json`):
There are two options to provide identity schemas:

Note: You are free to name `<schema-id>` and `<schema-name>` whatever you want.

1. Write json to `kratos.identitySchemas`:

```yaml
kratos:
identitySchemas:
user.schema.json: |-
<schema-name>.schema.json: |-
{
"$id": "..."
}
config:
identity:
schemas:
- id: <schema-id>
# match the name of the identitySchema
url: file:///etc/config/<schema-name>.schema.json
```

2. Pass file using `--set-file` Helm CLI argument:

Firstly, set file to `<your-key>`:

```bash
helm install kratos ory/kratos \
--values "/your/values" \
--set-file <your-key>=/path/to/user.schema.json
```

Next use it on `kratos.identitySchemas`:
2. Encode json schema in base64
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will verify this part myself, please don't remove yet :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let me know how it goes. I will update the doc accordingly

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi there, sorry it took so much time 😞. Anyway, the feature works as expected, with the following values.yaml snippet:

---
autoscaling:
  enabled: false
kratos:
  automigration:
    enabled: true
    customCommand:
      - kratos
    customArgs:
      - "migrate"
      - "sql"
      - "-e"
      - "--yes"
      - "--config"
      - "/etc/config/kratos.yaml"
  identitySchemas:
    "identity.default.schema.json": |-
      {{ .Values.extraSchemas.foo }}
  config:
    # ciphers:
    #   algorithm: aes
    dsn: "postgres://postgres:ory@postgresql.default.svc.cluster.local/ory?sslmode=disable&max_conn_lifetime=10s"
    selfservice:
      default_browser_return_url: http://127.0.0.1:4455/
      methods:
        password:
          enabled: true
    log:
      level: debug
    secrets:
      default:
        - PLEASE-CHANGE-ME-I-AM-VERY-INSECURE
        - "OG5XbmxXa3dYeGplQXpQanYxeEFuRUFa"
        - "foo bar 123 456 lorem"
        - "foo bar 123 456 lorem 1"
        - "foo bar 123 456 lorem 2"
        - "foo bar 123 456 lorem 3"
    hashers:
      argon2:
        parallelism: 1
        memory: 128MB
        iterations: 2
        salt_length: 16
        key_length: 16
    identity:
      default_schema_id: default
      schemas:
        - id: default
          url: file:///etc/config/identity.default.schema.json
    courier:
      smtp:
        connection_uri: smtps://test:test@mailslurper:1025/?skip_ssl_verify=true

And installing it via:

helm install kratos ./helm/charts/kratos -f hacks/values/kratos.yaml --debug --atomic --set-file extraSchemas.foo=schema.json

The result is a configmap which holds the user specified schemas, taken from the file:

apiVersion: v1
data:
  identity.default.schema.json: |2-
          {
             "$id": "https://schemas.ory.sh/presets/kratos/identity.email.schema.json",
             "$schema": "http://json-schema.org/draft-07/schema#",
             "title": "Person",
             "type": "object",
             "properties": {
                "traits": {
                   "type": "object",
                   "properties": {
                      "email": {
                         "type": "string",
                         "format": "email",
                         "title": "E-Mail",
                         "ory.sh/kratos": {
                            "credentials": {
                               "password": {
                                  "identifier": true
                               }
                            },
                            "recovery": {
                               "via": "email"
                            },
                            "verification": {
                               "via": "email"
                            }
                         }
                      }
                   },
                   "required": [
                      "email"
                   ],
                   "additionalProperties": false
                }
             }
          }
  kratos.yaml: |
    courier:
      smtp: {}
    hashers:
      argon2:
        iterations: 2
        key_length: 16
        memory: 128MB
        parallelism: 1
        salt_length: 16
    identity:
      default_schema_id: default
      schemas:
      - id: default
        url: file:///etc/config/identity.default.schema.json
    log:
      level: debug
    selfservice:
      default_browser_return_url: http://127.0.0.1:4455/
      methods:
        password:
          enabled: true
    serve:
      admin:
        port: 4434
      public:
        port: 4433
kind: ConfigMap
metadata:
  annotations:
    meta.helm.sh/release-name: kratos
    meta.helm.sh/release-namespace: default
  creationTimestamp: "2022-10-04T07:14:43Z"
  labels:
    app.kubernetes.io/instance: kratos
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kratos
    app.kubernetes.io/version: v0.10.1
    helm.sh/chart: kratos-0.25.4
  name: kratos-config
  namespace: default
  resourceVersion: "887"
  uid: aa79b558-3c4b-40d1-8ca3-74036d035bdb

We may improve the wording here to reflect that both kratos.identitySchemas and kratos.config.identity.schemas need to be set

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for checking. I could install following your instructions. I updated the doc


```yaml
kratos:
identitySchemas:
user.schema.json: |-
{{ .Values.<your-key> }}
config:
identity:
schemas:
- id: <schema-id>
url: base64://<base64-encoded-json>
```

## Upgrade
Expand Down