https://helm.sh/assets/js/9c1a967f.847a292b.js

1"use strict";(self.webpackChunkhelm_www=self.webpackChunkhelm_www||[]).push([["14316"],{35936(e,t,n){n.r(t),n.d(t,{metadata:()=>a,default:()=>h,frontMatter:()=>i,contentTitle:()=>r,toc:()=>o,assets:()=>c});var a=JSON.parse('{"id":"chart_template_guide/getting_started","title":"Getting Started","description":"A quick guide on Chart templates.","source":"@site/versioned_docs/version-3/chart_template_guide/getting_started.md","sourceDirName":"chart_template_guide","slug":"/chart_template_guide/getting_started","permalink":"/docs/v3/chart_template_guide/getting_started","draft":false,"unlisted":false,"editUrl":"https://github.com/helm/helm-www/blob/main/versioned_docs/version-3/chart_template_guide/getting_started.md","tags":[],"version":"3","sidebarPosition":2,"frontMatter":{"title":"Getting Started","description":"A quick guide on Chart templates.","sidebar_position":2},"sidebar":"tutorialSidebar","previous":{"title":"Chart Template Guide","permalink":"/docs/v3/chart_template_guide/"},"next":{"title":"Built-in Objects","permalink":"/docs/v3/chart_template_guide/builtin_objects"}}'),l=n(74848),s=n(28453);let i={title:"Getting Started",description:"A quick guide on Chart templates.",sidebar_position:2},r,c={},o=[{value:"Charts",id:"charts",level:2},{value:"A Starter Chart",id:"a-starter-chart",level:2},{value:"A Quick Glimpse of <code>mychart/templates/</code>",id:"a-quick-glimpse-of-mycharttemplates",level:3},{value:"A First Template",id:"a-first-template",level:2},{value:"Adding a Simple Template Call",id:"adding-a-simple-template-call",level:3}];function d(e){let t={a:"a",blockquote:"blockquote",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsx)(t.p,{children:"In this section of the guide, we'll create a chart and then add a first\ntemplate. The chart we created here will be used throughout the rest of the\nguide."}),"\n",(0,l.jsx)(t.p,{children:"To get going, let's take a brief look at a Helm chart."}),"\n",(0,l.jsx)(t.h2,{id:"charts",children:"Charts"}),"\n",(0,l.jsxs)(t.p,{children:["As described in the ",(0,l.jsx)(t.a,{href:"/docs/v3/topics/charts",children:"Charts Guide"}),", Helm charts are\nstructured like this:"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{children:"mychart/\n  Chart.yaml\n  values.yaml\n  charts/\n  templates/\n  ...\n"})}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"templates/"})," directory is for template files. When Helm evaluates a chart,\nit will send all of the files in the ",(0,l.jsx)(t.code,{children:"templates/"})," directory through the template\nrendering engine. It then collects the results of those templates and sends them\non to Kubernetes."]}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"values.yaml"})," file is also important to templates. This file contains the\n",(0,l.jsx)(t.em,{children:"default values"})," for a chart. These values may be overridden by users during\n",(0,l.jsx)(t.code,{children:"helm install"})," or ",(0,l.jsx)(t.code,{children:"helm upgrade"}),"."]}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"Chart.yaml"})," file contains a description of the chart. You can access it\nfrom within a template."]}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"charts/"})," directory ",(0,l.jsx)(t.em,{children:"may"})," contain other charts\n(which we call ",(0,l.jsx)(t.em,{children:"subcharts"}),"). Later in this guide we will see how those work when\nit comes to template rendering."]}),"\n",(0,l.jsx)(t.h2,{id:"a-starter-chart",children:"A Starter Chart"}),"\n",(0,l.jsxs)(t.p,{children:["For this guide, we'll create a simple chart called ",(0,l.jsx)(t.code,{children:"mychart"}),", and then we'll\ncreate some templates inside of the chart."]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-console",children:"$ helm create mychart\nCreating mychart\n"})}),"\n",(0,l.jsxs)(t.h3,{id:"a-quick-glimpse-of-mycharttemplates",children:["A Quick Glimpse of ",(0,l.jsx)(t.code,{children:"mychart/templates/"})]}),"\n",(0,l.jsxs)(t.p,{children:["If you take a look at the ",(0,l.jsx)(t.code,{children:"mychart/templates/"})," directory, you'll notice a few\nfiles already there."]}),"\n",(0,l.jsxs)(t.ul,{children:["\n",(0,l.jsxs)(t.li,{children:[(0,l.jsx)(t.code,{children:"NOTES.txt"}),': The "help text" for your chart. This will be displayed to your\nusers when they run ',(0,l.jsx)(t.code,{children:"helm install"}),"."]}),"\n",(0,l.jsxs)(t.li,{children:[(0,l.jsx)(t.code,{children:"deployment.yaml"}),": A basic manifest for creating a Kubernetes\n",(0,l.jsx)(t.a,{href:"https://kubernetes.io/docs/concepts/workloads/controllers/deployment/",children:"deployment"})]}),"\n",(0,l.jsxs)(t.li,{children:[(0,l.jsx)(t.code,{children:"service.yaml"}),": A basic manifest for creating a ",(0,l.jsx)(t.a,{href:"https://kubernetes.io/docs/concepts/services-networking/service/",children:"service\nendpoint"})," for your deployment"]}),"\n",(0,l.jsxs)(t.li,{children:[(0,l.jsx)(t.code,{children:"_helpers.tpl"}),": A place to put template helpers that you can re-use throughout\nthe chart"]}),"\n"]}),"\n",(0,l.jsxs)(t.p,{children:["And what we're going to do is... ",(0,l.jsx)(t.em,{children:"remove them all!"}

1)," That way we can work through\nour tutorial from scratch. We'll actually create our own ",(0,l.jsx)(t.code,{children:"NOTES.txt"})," and\n",(0,l.jsx)(t.code,{children:"_helpers.tpl"})," as we go."]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-console",children:"$ rm -rf mychart/templates/*\n"})}),"\n",(0,l.jsx)(t.p,{children:"When you're writing production grade charts, having basic versions of these\ncharts can be really useful. So in your day-to-day chart authoring, you probably\nwon't want to remove them."}),"\n",(0,l.jsx)(t.h2,{id:"a-first-template",children:"A First Template"}),"\n",(0,l.jsxs)(t.p,{children:["The first template we are going to create will be a ",(0,l.jsx)(t.code,{children:"ConfigMap"}),". In Kubernetes,\na ConfigMap is simply an object for storing configuration data. Other things,\nlike pods, can access the data in a ConfigMap."]}),"\n",(0,l.jsx)(t.p,{children:"Because ConfigMaps are basic resources, they make a great starting point for us."}),"\n",(0,l.jsxs)(t.p,{children:["Let's begin by creating a file called ",(0,l.jsx)(t.code,{children:"mychart/templates/configmap.yaml"}),":"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-yaml",children:'apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: mychart-configmap\ndata:\n  myvalue: "Hello World"\n'})}),"\n",(0,l.jsxs)(t.p,{children:[(0,l.jsx)(t.strong,{children:"TIP:"})," Template names do not follow a rigid naming pattern. However, we\nrecommend using the extension ",(0,l.jsx)(t.code,{children:".yaml"})," for YAML files and ",(0,l.jsx)(t.code,{children:".tpl"})," for helpers."]}),"\n",(0,l.jsxs)(t.p,{children:["The YAML file above is a bare-bones ConfigMap, having the minimal necessary\nfields. By virtue of the fact that this file is in the ",(0,l.jsx)(t.code,{children:"mychart/templates/"}),"\ndirectory, it will be sent through the template engine."]}),"\n",(0,l.jsxs)(t.p,{children:["It is just fine to put a plain YAML file like this in the ",(0,l.jsx)(t.code,{children:"mychart/templates/"}),"\ndirectory. When Helm reads this template, it will simply send it to Kubernetes\nas-is."]}),"\n",(0,l.jsx)(t.p,{children:"With this simple template, we now have an installable chart. And we can install\nit like this:"}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-console",children:"$ helm install full-coral ./mychart\nNAME: full-coral\nLAST DEPLOYED: Tue Nov  1 17:36:01 2016\nNAMESPACE: default\nSTATUS: DEPLOYE

1D\nREVISION: 1\nTEST SUITE: None\n"})}),"\n",(0,l.jsx)(t.p,{children:"Using Helm, we can retrieve the release and see the actual template that was\nloaded."}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-console",children:'$ helm get manifest full-coral\n\n---\n# Source: mychart/templates/configmap.yaml\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: mychart-configmap\ndata:\n  myvalue: "Hello World"\n'})}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"helm get manifest"})," command takes a release name (",(0,l.jsx)(t.code,{children:"full-coral"}),") and prints\nout all of the Kubernetes resources that were uploaded to the server. Each file\nbegins with ",(0,l.jsx)(t.code,{children:"---"})," to indicate the start of a YAML document, and then is followed\nby an automatically generated comment line that tells us what template file\ngenerated this YAML document."]}),"\n",(0,l.jsxs)(t.p,{children:["From there on, we can see that the YAML data is exactly what we put in our\n",(0,l.jsx)(t.code,{children:"configmap.yaml"})," file."]}),"\n",(0,l.jsxs)(t.p,{children:["Now we can uninstall our release: ",(0,l.jsx)(t.code,{children:"helm uninstall full-coral"}),"."]}),"\n",(0,l.jsx)(t.h3,{id:"adding-a-simple-template-call",children:"Adding a Simple Template Call"}),"\n",(0,l.jsxs)(t.p,{children:["Hard-coding the ",(0,l.jsx)(t.code,{children:"name:"})," into a resource is usually considered to be bad\npractice. Names should be unique to a release. So we might want to generate a\nname field by inserting the release name."]}),"\n",(0,l.jsxs)(t.p,{children:[(0,l.jsx)(t.strong,{children:"TIP:"})," The ",(0,l.jsx)(t.code,{children:"name:"})," field is limited to 63 characters because of limitations to\nthe DNS system. For that reason, release names are limited to 53 characters.\nKubernetes 1.3 and earlier limited to only 24 characters (thus 14 character\nnames)."]}),"\n",(0,l.jsxs)(t.p,{children:["Let's alter ",(0,l.jsx)(t.code,{children:"configmap.yaml"})," accordingly."]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-yaml",children:'apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: {{ .Release.Name }}-configmap\ndata:\n  myvalue: "Hello World"\n'})}),"\n",(0,l.jsxs)(t.p,{children:["The big change comes in the value of the ",(0,l.jsx)(t.code,{children:"name:"})," field, which is now\n",(0,l.jsx)(t.code,{children:"{{ .Release.Name }}-configmap"}),"."]}),"\n",(0,l.jsxs)(t.blockquote,{children:["\n",(0,l.jsxs)(t.p,{children:["A template directive is enclosed in ",(0,l.jsx)(t.code,{children:"{{"})," and ",(0,l.jsx)(t.code,{children:"}}"})," blocks."]}),"\n"]}),"\n",(0,l.jsxs)(t.p,{children:["The template directive ",(0,l.jsx)(t.code,{children:"{{ .Release.Name }}"})," injects the release name into the\ntemplate. The values that are passed into a template can be thought of as\n",(0,l.jsx)(t.em,{children:"namespaced objects"}),", where a dot (",(0,l.jsx)(t.code,{children:"."}),") separates each namespaced element."]}),"\n",(0,l.jsxs)(t.p,{children:["The leading dot before ",(0,l.jsx)(t.code,{children:"Release"})," indicates that we start with the top-most\nnamespace for this scope (we'll talk about scope in a bit). So we could read\n",(0,l.jsx)(t.code,{children:".Release.Name"}),' as "start at the top namespace, find the ',(0,l.jsx)(t.code,{children:"Release"})," object, then\nlook inside of it for an object called ",(0,l.jsx)(t.code,{children:"Name"}),'".']}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"Release"})," object is one of the built-in objects for Helm, and we'll cover it\nin more depth later. But for now, it is sufficient to say that this will display\nthe release name that the library assigns to our release."]}),"\n",(0,l.jsx)(t.p,{children:"Now when we install our resource, we'll immediately see the result of using this\ntemplate directive:"}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-console",children:"$ helm install clunky-serval ./mychart\nNAME: clunky-serval\nLAST DEPLOYED: Tue Nov  1 17:45:37 2016\nNAMESPACE: default\nSTATUS: DEPLOYE

1D\nREVISION: 1\nTEST SUITE: None\n"})}),"\n",(0,l.jsxs)(t.p,{children:["You can run ",(0,l.jsx)(t.code,{children:"helm get manifest clunky-serval"})," to see the entire generated YAML."]}),"\n",(0,l.jsxs)(t.p,{children:["Note that the ConfigMap inside Kubernetes name is ",(0,l.jsx)(t.code,{children:"clunky-serval-configmap"}),"\ninstead of ",(0,l.jsx)(t.code,{children:"mychart-configmap"})," previously."]}),"\n",(0,l.jsxs)(t.p,{children:["At this point, we've seen templates at their most basic: YAML files that have\ntemplate directives embedded in ",(0,l.jsx)(t.code,{children:"{{"})," and ",(0,l.jsx)(t.code,{children:"}}"}),". In the next part, we'll take a\ndeeper look into templates. But before moving on, there's one quick trick that\ncan make building templates faster: When you want to test the template\nrendering, but not actually install anything, you can use ",(0,l.jsx)(t.code,{children:"helm install --debug --dry-run goodly-guppy ./mychart"}),". This will render the templates. But instead\nof installing the chart, it will return the rendered template to you so you can\nsee the output:"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-console",children:'$ helm install --debug --dry-run goodly-guppy ./mychart\ninstall.go:149: [debug] Original chart version: ""\ninstall.go:166: [debug] CHART PATH: /Users/ninja/mychart\n\nNAME: goodly-guppy\nLAST DEPLOYED: Thu Dec 26 17:24:13 2019\nNAMESPACE: default\nSTATUS: pending-install\nREVISION: 1\nTEST SUITE: None\nUSER-SUPPLIED VALUES:\n{}\n\nCOMPUTED VALUES:\naffinity: {}\nfullnameOverride: ""\nimage:\n  pullPolicy: IfNotPresent\n  repository: nginx\nimagePullSecrets: []\ningress:\n  annotations: {}\n  enabled: false\n  hosts:\n  - host: chart-example.local\n    paths: []\n  tls: []\nnameOverride: ""\nnodeSelector: {}\npodSecurityContext: {}\nreplicaCount: 1\nresources: {}\nsecurityContext: {}\nservice:\n  port: 80\n  type: ClusterIP\nserviceAccount:\n  create: true\n  name: null\ntolerations: []\n\nHOOKS:\nMANIFEST:\n---\n# Source: mychart/templates/configmap.yaml\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: goodly-guppy-configmap\ndata:\n  myvalue: "Hello World"\n\n'})}),"\n",(0,l.jsxs)(t.p,{children:["Using ",(0,l.jsx)(t.code,{children:"--dry-run"})," will make it easier to test your code, but it won't ensure\nthat Kubernetes itself will accept the templates you generate. It's best not to\nassume that your chart will install just because ",(0,l.jsx)(t.code,{children:"--dry-run"})," works."]}),"\n",(0,l.jsxs)(t.p,{children:["In the ",(0,l.jsx)(t.a,{href:"/docs/v3/chart_template_guide/",children:"Chart Template Guide"}),", we take the basic chart we defined\nhere and explore the Helm template language in detail. And we'll get started\nwith built-in objects."]})]})}function h(e={}){let{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,l.jsx)(t,{...e,children:(0,l.jsx)(d,{...e})}):d(e)}},28453(e,t,n){n.d(t,{R:()=>i,x:()=>r});var a=n(96540);let l={},s=a.createContext(l);function i(e){let t=a.useContext(s);return a.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:i(e.components),a.createElement(s.Provider,{value:t},e.children)}}}]);