Skip to content

Latest commit

 

History

History
1108 lines (1052 loc) · 25.7 KB

README.md

File metadata and controls

1108 lines (1052 loc) · 25.7 KB
Raw

django

Version: 0.2.1 AppVersion: 3.1

Generic chart for basic Django-based web app

Homepage: https://www.djangoproject.com/

Maintainers

Name Email Url
Rizky Maulana Nugraha lana.pcfre@gmail.com

Source Code

Requirements

Repository Name Version
file://../../common/v1.0.0 common 1.0.0
file://../../postgis/v0.2.1 postgis 0.2.1

Some Long Description

This is a sample README with custom overrides. Check the template in README.md.gotmpl.

In that file, we redefine the template definition of chart.valueDefaultColumnRender for some custom @notationType such as string/email.

This chart README uses chart.valuesSectionHtml instead of chart.valuesSection. Using HTML table directly instead of using Markdown table allows us to control the table presentation, such as the height. This is especially useful for very long values.yaml file, and you need to scroll both horizontally and vertically to navigate the values.

In the template file, we redefine chart.valuesTableHtml so that we use table height of 400px at most. Github can understand that attribute. The more sophisticated use case is if you want to combine helm-docs with a Jamstack static generator where you can have your own page generated from this README.

The customization can goes even further. Normally, you can't define anchor in markdown unless it is a heading. But you can do so easily using HTML tags. You can override the column key renderer by adding an id attribute so that it can be referred. This way, when you write markdown links like ingress.tls.secretName, clicking the link will take you to the value description row.

Value Types

One of the benefit of using HTML table is we can make a simple tooltip and anchor. For example, the value global.adminEmail is annotated as type string/email. We create the definition of the value type here and can be anchored by links with #stringemail hyperlinks.

We can also create custom type column renderer, where we can assign a tooltip for each type. Try this out. Go navigate to global.adminEmail value, hover on the value type string/email, you will then see some tooltip. Clicking the type link will direct you back to it's relevant value type section below.

Other useful case is If the type is a known type, like Kubernetes service type, you can anchor the type to redirect user to k8s documentation page to learn more. Check the value persistence.staticDir.accessModes

string/email

This value type is for a valid email address format. Such as owner@somedomain.org.

Notation Type

Another reason to use HTML table is because in some cases we want to custom-render the default value.

In helm chart templates, sometimes author designs the template to accept a go template string value. That means, the template string can be processed by helm chart and be replaced with dynamic computed values, before it was rendered to the chart. Although it is very useful and flexible to make the default value be dynamic, it is not entirely obvious for the chart users to see a go template as value in a values.yml. It would then be helpful to custom-render these default values in the helm README, so that it is not treated as a pure JSON object (because the syntax highlighter would be incorrect). Instead we can custom render the presentation so it would make sense to the user.

In our example here, any key with a type tpl/xxx would be rendered as <pre></pre> HTML tag, in which we both put the key name and the YAML multiline modifier | to make it really clear that the key accept a multiline string as value, because it would be rendered as YAML object by helm after the values are interpolated/substituted.

Take a look at extraPodEnv. The Default column shows the key name extraPodEnv, the multiline YAML modifier |, and the template string which contains some go string template syntax {{ }}.

You can also control the HTML styling directly. In some markdown viewer, the HTML tag and inline styles are respected, so the custom styles can be seen. Combined with a Jamstack approach, you can design your template to also incorporate some custom React styles or simple CSS.

In our example here, global.adminEmail is annotated with email notationType. This allows you to insert custom rendering code for email. For supported markdown viewer, like Visual Studio Code, the default value will have green color, and if clicked will direct you to your default email composer.

The reason we have two separate annotation, value type and notation type, is because several different types can have the same type renderer. For example, any type tpl/xxx is a go template string, so it will be rendered the same in our docs if we annotate it with @notationType -- tpl.

Customized Rendering

This README also shows some possible customization with helm-docs. In the README.md.gotmpl file, you can see that we modified the column Key to also be hyperlinked with the definition in values.yaml. If you view this README.md files in GitHub and click the value's key, you will be directed to the key location in the values.yaml file.

You can also render a raw string into the comments using @raw annotations. You can jump to sampleYaml key and check it's description where it uses HTML <summary> tag to collapse some part of the comments.

Values

Key Type Default Description
extraConfigMap tpl/dict 
extraConfigMap: |
 Define this for extra config map to be included in django-shared-config
extraPodEnv tpl/array 
extraPodEnv: |
  - name: DJANGO_SETTINGS_MODULE
    value: "django.settings"
  - name: DEBUG
    value: {{ .Values.global.debug | quote }}
  - name: ROOT_URLCONF
    value: {{ .Values.global.rootURLConf | quote }}
  - name: MAIN_APP_NAME
    value: {{ .Values.global.mainAppName | quote }}
 Define this for extra Django environment variables
extraPodSpec tpl/object 
extraPodSpec: |
 This will be evaluated as pod spec
extraSecret tpl/dict 
extraSecret: |
 Define this for extra secrets to be included in django-shared-secret secret
extraVolume tpl/array 
extraVolume: |
 Define this for extra volume (in pair with extraVolumeMounts)
extraVolumeMounts tpl/array 
extraVolumeMounts: |
 Define this for extra volume mounts in the pod
global object 
{
  "adminEmail": "admin@localhost",
  "adminPassword": {
    "value": null,
    "valueFrom": {
      "secretKeyRef": {
        "key": "admin-password",
        "name": null
      }
    }
  },
  "adminUser": "admin",
  "databaseHost": "postgis",
  "databaseName": "django",
  "databasePassword": {
    "value": null,
    "valueFrom": {
      "secretKeyRef": {
        "key": "database-password",
        "name": null
      }
    }
  },
  "databasePort": 5432,
  "databaseUsername": "django_db_user",
  "debug": "False",
  "djangoArgs": "[\"uwsgi\",\"--chdir=${REPO_ROOT}\",\"--module=${MAIN_APP_NAME}.wsgi\",\"--socket=:8000\",\"--http=0.0.0.0:8080\",\"--processes=5\",\"--buffer-size=8192\"]\n",
  "djangoCommand": "[\"/opt/django/scripts/docker-entrypoint.sh\"]\n",
  "djangoSecretKey": {
    "value": null,
    "valueFrom": {
      "secretKeyRef": {
        "key": "django-secret",
        "name": null
      }
    }
  },
  "djangoSettingsModule": "django.settings",
  "existingSecret": "",
  "mainAppName": "django",
  "mediaRoot": "/opt/django/media",
  "nameOverride": "django",
  "rootURLConf": "django.urls",
  "sharedSecretName": "django-shared-secret",
  "siteName": "django",
  "staticRoot": "/opt/django/static"
}
 This key name is used for service interconnection between subcharts and parent charts.
global.adminEmail string/email Default admin email sender
global.adminPassword.value string 
null
 Specify this password value. If not, it will be autogenerated everytime chart upgraded
global.adminUser string 
"admin"
 Default super user admin username
global.databaseHost string 
"postgis"
 Django database host location. By default this chart can generate standard postgres chart. So you can leave it as default. If you use external backend, you must provide the value
global.databaseName string 
"django"
 Django database name
global.databasePassword.value string 
null
 Specify this password value. If not, it will be autogenerated everytime chart upgraded. If you use external backend, you must provide the value
global.databasePort int 
5432
 Django database port. By default this chart can generate standard postgres chart. So you can leave it as default. If you use external backend, you must provide the value
global.databaseUsername string 
"django_db_user"
 Database username backend to connect to. If you use external backend, provide the value
global.debug string 
"False"
 Python boolean literal, this will correspond to `DEBUG` environment variable inside the Django container. Useful as a debug switch.
global.djangoArgs tpl/array 
global.djangoArgs: |
  ["uwsgi","--chdir=${REPO_ROOT}","--module=${MAIN_APP_NAME}.wsgi","--socket=:8000","--http=0.0.0.0:8080","--processes=5","--buffer-size=8192"]
 The django command args to be passed to entrypoint command
global.djangoCommand tpl/array 
global.djangoCommand: |
  ["/opt/django/scripts/docker-entrypoint.sh"]
 The django entrypoint command to execute
global.djangoSecretKey.value string 
null
 Specify this Django Secret string value. If not, it will be autogenerated everytime chart upgraded
global.djangoSettingsModule string 
"django.settings"
 Django settings module to be used
global.existingSecret tpl/string 
global.existingSecret: |
 Name of existing secret
global.mainAppName string 
"django"
 The main app name to execute. Affects which settings, wsgi, and rootURL to use.
global.mediaRoot path 
"/opt/django/media"
 Location to the media directory
global.rootURLConf string 
"django.urls"
 Django root URL conf to be used
global.sharedSecretName string 
"django-shared-secret"
 Name of shared secret store that will be generated
global.siteName string 
"django"
 The site name. It will be used to construct url such as http://django/
global.staticRoot path 
"/opt/django/static"
 Location to the static directory
image object 
{
  "pullPolicy": "IfNotPresent",
  "registry": "docker.io",
  "repository": "lucernae/django-sample",
  "tag": "3.1"
}
 Image map
image.pullPolicy string 
"IfNotPresent"
 Image pullPolicy
image.registry string 
"docker.io"
 Image registry
image.repository string 
"lucernae/django-sample"
 Image repository
image.tag string 
"3.1"
 Image tag
ingress.annotations dict 
{}
 Custom Ingress annotations
ingress.enabled bool 
false
 Set to true to generate Ingress resource
ingress.host tpl/string 
ingress.host: |
 Set custom host name. (DNS name convention)
ingress.labels dict 
{}
 Custom Ingress labels
ingress.tls.enabled bool 
false
 Set to true to enable HTTPS
ingress.tls.secretName string 
"django-tls"
 You must provide a secret name where the TLS cert is stored
labels map 
user/workload: "true"
client-name: "my-boss"
project-name: "awesome-project"
 The deployment label
persistence.mediaDir.accessModes[0] string 
"ReadWriteOnce"
persistence.mediaDir.annotations object 
{}
persistence.mediaDir.enabled bool 
true
 Allow persistence
persistence.mediaDir.existingClaim bool 
false
persistence.mediaDir.mountPath string 
"/opt/django/media"
persistence.mediaDir.size string 
"8Gi"
persistence.mediaDir.subPath string 
"media"
persistence.staticDir.accessModes k8s/storage/persistent-volume/access-modes 
- ReadWriteOnce
 Static Dir access modes
persistence.staticDir.annotations object 
{}
persistence.staticDir.enabled bool 
true
 Allow persistence
persistence.staticDir.existingClaim bool 
false
persistence.staticDir.mountPath string 
"/opt/django/static"
persistence.staticDir.size string 
"8Gi"
persistence.staticDir.subPath string 
"static"
postgis.enabled bool 
true
 Enable postgis as database backend by default. Set to false if using different external backend.
postgis.existingSecret tpl/string 
postgis.existingSecret: |
  {{ include "common.sharedSecretName" . | quote -}}
 Existing secret to be used
probe tpl/object 
probe: |
 Probe can be overridden
sampleYaml dict 
{}
 Values with long description Sometimes you need a very long description for your values.

Any comment section for a given key with @raw attribute will be treated as raw string and stored as is. Since it generates in Markdown format, you can do something like this:

hello:
  bar: true

Markdown also accept subset of HTML tags. So you can also do this:

+Expand 
execute some command
service.annotations dict 
{}
 Extra service annotations
service.clusterIP string 
""
 Specify `None` for headless service. Otherwise, leave them be.
service.externalIPs tpl/array 
service.externalIPs: |
 Specify for LoadBalancer service type
service.nodePort int 
null
 Specify node port, for NodePort service type
service.port int 
80
 Specify service port
service.type string 
"ClusterIP"
 Define k8s service for Django.

Autogenerated from chart metadata using helm-docs v1.14.0