package templatebuilder import ( "archive/tar" "bytes" "maps" "path" "slices" "time" "github.com/hashicorp/hcl/v2/hclwrite" "golang.org/x/xerrors" "github.com/coder/coder/v2/codersdk" ) // ComposeRequest describes which base template and modules to render. type ComposeRequest struct { BaseTemplateID string // BaseVariableValues maps base template variable names to their // user-supplied values. BaseVariableValues map[string]string // RegistryURL is the module registry base URL from the deployment // config (CODER_TEMPLATE_BUILDER_REGISTRY_URL). RegistryURL string Modules []ComposeModule } // ComposeModule identifies a module to include and the variable values // to render into its module block. type ComposeModule struct { ID string // AgentName is the base coder_agent the module attaches to; empty uses the // base default. Must name an agent the base declares. AgentName string // Variables maps variable names to HCL literal values for // non-sensitive, non-computed variables. Variables map[string]string } // ComposeResult holds the rendered Terraform files ready for bundling. type ComposeResult struct { // MainTF is the rendered base template. MainTF []byte // ModulesTF is the concatenated rendered module blocks. Empty when // no modules are selected. ModulesTF []byte // Readme is the full README.md content from the base template. // Empty when the base has no README. Readme []byte // ExtraFiles holds non-template files from the base directory // (e.g. cloud-init .tftpl files). Keys are paths relative to the // base directory. ExtraFiles map[string][]byte } // Compose renders a base template and the selected modules into Terraform // source files. func Compose(req ComposeRequest) (*ComposeResult, error) { // Validated at server start (codersdk.DeploymentValues.Validate). Normalize // here too so a direct caller that bypasses the boot check gets the same // scheme-stripping and rejection; default an unset value. registryBase, err := codersdk.NormalizeTemplateBuilderRegistryURL(req.RegistryURL) if err != nil { return nil, err } if registryBase == "" { registryBase = DefaultRegistryBase } mainTF, err := renderBase(req.BaseTemplateID, req.BaseVariableValues, registryBase) if err != nil { return nil, err } extraFiles := BaseExtraFiles(req.BaseTemplateID) if len(req.Modules) == 0 { return &ComposeResult{ MainTF: formatHCL(mainTF), Readme: composedReadme(req.BaseTemplateID), ExtraFiles: extraFiles, }, nil } extractedAgents, err := ExtractAgentResourceNames(mainTF) if err != nil { return nil, xerrors.Errorf("extract agents: %w", err) } if len(extractedAgents) == 0 { return nil, xerrors.New("no coder_agent resource found in rendered template") } agentRefByName := make(map[string]string, len(extractedAgents)) for _, a := range extractedAgents { agentRefByName[a.Name] = a.Reference } // Bases that declare no agents fall back to the first rendered agent. defaultName := BaseDefaultAgentName(req.BaseTemplateID) if defaultName == "" { defaultName = extractedAgents[0].Name } catalog, err := loadCatalogMap() if err != nil { return nil, err } baseOS := BaseTemplateOS(req.BaseTemplateID) baseModules := BaseIncludedModules(req.BaseTemplateID) if err := validateModules(req.Modules, catalog, baseOS, baseModules); err != nil { return nil, err } modulesTF, err := renderModules(req.Modules, catalog, registryBase, agentRefByName, defaultName) if err != nil { return nil, err } result := &ComposeResult{ MainTF: formatHCL(mainTF), ModulesTF: formatHCL(modulesTF), Readme: composedReadme(req.BaseTemplateID), ExtraFiles: extraFiles, } return result, nil } // composedReadme returns the base README prepared for delivery in the // output archive. The prerequisites markers are stripped so they do not // render as literal text when the README is viewed. Returns nil when the // base has no README. func composedReadme(baseTemplateID string) []byte { readme := StripPrerequisitesMarkers(BaseReadme(baseTemplateID)) if readme == "" { return nil } return []byte(readme) } // formatHCL applies canonical HCL formatting to src. If src is not valid // HCL the input is returned unchanged. func formatHCL(src []byte) []byte { if len(src) == 0 { return src } return hclwrite.Format(src) } // renderBase renders the base template for the given example ID, // merging any user-supplied variable values into the render context. func renderBase(baseTemplateID string, baseVars map[string]string, registryBase string) ([]byte, error) { renderCtx := DefaultBaseRenderContext(baseTemplateID) if renderCtx.Variables == nil { renderCtx.Variables = make(map[string]string) } renderCtx.RegistryBase = registryBase vars, err := mergeBaseVariables(baseTemplateID, baseVars) if err != nil { return nil, xerrors.Errorf("base %q: %w", baseTemplateID, err) } maps.Copy(renderCtx.Variables, vars) mainTF, err := RenderBaseTemplate(baseTemplateID, "main.tf.tmpl", renderCtx) if err != nil { return nil, xerrors.Errorf("render base template: %w", err) } return mainTF, nil } // mergeBaseVariables builds the final Variables map for a base template. // It starts with manifest defaults, overlays caller-supplied values, // validates types, and converts to HCL literals. func mergeBaseVariables(baseTemplateID string, callerVars map[string]string) (map[string]string, error) { allVars := BaseVariables(baseTemplateID) if len(allVars) == 0 && len(callerVars) == 0 { return make(map[string]string), nil } allowedVars := make(map[string]ModuleVariable, len(allVars)) for _, v := range allVars { if v.Computed || v.Sensitive { continue } allowedVars[v.Name] = v } // Validate caller-supplied keys and values. for k, val := range callerVars { v, ok := allowedVars[k] if !ok { return nil, xerrors.Errorf("unknown variable %q", k) } if err := validateVariableValue(v, val); err != nil { return nil, xerrors.Errorf("variable %q: %w", k, err) } } // Build merged map from manifest defaults. merged := make(map[string]string, len(allVars)) for _, v := range allVars { if v.Computed || v.Sensitive { continue } if len(v.Default) > 0 && isSimpleJSONValue(v.Default) { merged[v.Name] = string(v.Default) } } // Overlay validated caller values, converting to HCL literals. for k, val := range callerVars { merged[k] = toHCLLiteral(allowedVars[k], val) } // Ensure all required variables without defaults have a value. for _, v := range allVars { if v.Computed || v.Sensitive { continue } if v.Required && merged[v.Name] == "" { return nil, xerrors.Errorf("variable %q is required", v.Name) } } return merged, nil } // loadCatalogMap loads the module catalog and returns it as a map keyed // by module ID. func loadCatalogMap() (map[string]ModuleManifest, error) { modules, err := LoadModules() if err != nil { return nil, xerrors.Errorf("load module catalog: %w", err) } catalog := make(map[string]ModuleManifest, len(modules)) for _, m := range modules { catalog[m.ID] = m } return catalog, nil } // validateModules checks that all requested modules exist, are // OS-compatible, have no duplicates, do not collide with a module the base // already includes (see BaseIncludedModules), and have no conflicts. func validateModules(requested []ComposeModule, catalog map[string]ModuleManifest, baseOS BaseOS, baseModules []string) error { // Seed the seen-set with the modules the base already declares so the // base and wizard-selected modules occupy a disjoint namespace. seen := make(map[string]bool, len(requested)+len(baseModules)) baseIncluded := make(map[string]bool, len(baseModules)) for _, id := range baseModules { seen[id] = true baseIncluded[id] = true } for _, cm := range requested { if baseIncluded[cm.ID] { return xerrors.Errorf("module %q is already included by this base template", cm.ID) } if seen[cm.ID] { return xerrors.Errorf("duplicate module %q", cm.ID) } seen[cm.ID] = true manifest, ok := catalog[cm.ID] if !ok { return xerrors.Errorf("unknown module %q", cm.ID) } if !manifest.CompatibleWithOS(string(baseOS)) { return xerrors.Errorf("module %q is not compatible with OS %q", cm.ID, baseOS) } } // Reject a requested module whose ConflictsWith names an already-seen // module. Every requested module is in `seen` by now, so order does not // matter, and base-included modules seed `seen` too. A base-included // module's own ConflictsWith list is not consulted, which is safe because // base modules are curated. for _, cm := range requested { manifest := catalog[cm.ID] for _, conflict := range manifest.ConflictsWith { if seen[conflict] { return xerrors.Errorf("module %q conflicts with %q", cm.ID, conflict) } } } return nil } // renderModules renders the selected module blocks, each attached to its // resolved agent. func renderModules( requested []ComposeModule, catalog map[string]ModuleManifest, registryURL string, agentRefByName map[string]string, defaultName string, ) ([]byte, error) { var buf bytes.Buffer for _, cm := range requested { manifest := catalog[cm.ID] agentName := cm.AgentName if agentName == "" { agentName = defaultName } agentRef, ok := agentRefByName[agentName] if !ok { return nil, xerrors.Errorf("module %q references unknown agent %q", cm.ID, agentName) } modFS, err := ModuleTemplateFS(cm.ID) if err != nil { return nil, xerrors.Errorf("module template FS for %q: %w", cm.ID, err) } vars, err := mergeModuleVariables(manifest, cm.Variables) if err != nil { return nil, xerrors.Errorf("module %q: %w", cm.ID, err) } modCtx := ModuleRenderContext{ RegistryBase: registryURL, PinnedVersion: manifest.PinnedVersion, AgentResourceName: agentRef, Variables: vars, } rendered, err := RenderModuleTemplate(modFS, cm.ID+".tf.tmpl", modCtx) if err != nil { return nil, xerrors.Errorf("render module %q: %w", cm.ID, err) } if buf.Len() > 0 { _ = buf.WriteByte('\n') } _, _ = buf.Write(rendered) } return buf.Bytes(), nil } // mergeModuleVariables builds the final Variables map for a module template. // It starts with manifest defaults for all non-computed, non-sensitive // variables, then overlays caller-supplied values. Caller-supplied keys // are validated against the manifest and values are checked for type // correctness before being accepted. func mergeModuleVariables(manifest ModuleManifest, callerVars map[string]string) (map[string]string, error) { // Build lookup structures for the manifest variables. allowedVars := make(map[string]ModuleVariable, len(manifest.Variables)) for _, v := range manifest.Variables { if v.Computed || v.Sensitive { continue } allowedVars[v.Name] = v } // Validate caller-supplied keys and values before merging. for k, val := range callerVars { v, ok := allowedVars[k] if !ok { return nil, xerrors.Errorf("unknown variable %q", k) } if err := validateVariableValue(v, val); err != nil { return nil, xerrors.Errorf("variable %q: %w", k, err) } } // Build merged map from manifest defaults. merged := make(map[string]string, len(manifest.Variables)) for _, v := range manifest.Variables { if v.Computed || v.Sensitive { continue } if len(v.Default) > 0 && isSimpleJSONValue(v.Default) { // json.RawMessage values for simple types (e.g. `""`, // `false`, `13337`) are valid HCL literals. merged[v.Name] = string(v.Default) } else if !v.Required { // Non-required variables without an explicit default use // null, which tells Terraform to apply the module's own // default. merged[v.Name] = "null" } // Required variables without defaults are left out so that // missingkey=error surfaces the omission at render time. } // Overlay validated caller values, converting to HCL literals. for k, val := range callerVars { merged[k] = toHCLLiteral(allowedVars[k], val) } // Ensure all required variables without defaults have a value. for _, v := range manifest.Variables { if v.Computed || v.Sensitive { continue } if v.Required && merged[v.Name] == "" { return nil, xerrors.Errorf("variable %q is required", v.Name) } } return merged, nil } // BundleTar packages the compose result into a tar archive suitable for // the Coder file store. func BundleTar(result *ComposeResult) ([]byte, error) { if result == nil { return nil, xerrors.New("nil ComposeResult") } var buf bytes.Buffer tw := tar.NewWriter(&buf) if err := writeTarFile(tw, "main.tf", result.MainTF); err != nil { return nil, xerrors.Errorf("write main.tf to tar: %w", err) } if len(result.ModulesTF) > 0 { if err := writeTarFile(tw, "modules.tf", result.ModulesTF); err != nil { return nil, xerrors.Errorf("write modules.tf to tar: %w", err) } } if len(result.Readme) > 0 { if err := writeTarFile(tw, "README.md", result.Readme); err != nil { return nil, xerrors.Errorf("write README.md to tar: %w", err) } } // Write extra files in sorted order for reproducible archives. names := make([]string, 0, len(result.ExtraFiles)) for name := range result.ExtraFiles { names = append(names, name) } slices.Sort(names) // Emit directory entries for any subdirectories so that // extractors that do not implicitly create parents can // unpack the archive. dirs := make(map[string]bool) for _, name := range names { for dir := path.Dir(name); dir != "." && !dirs[dir]; dir = path.Dir(dir) { dirs[dir] = true } } sortedDirs := make([]string, 0, len(dirs)) for d := range dirs { sortedDirs = append(sortedDirs, d) } slices.Sort(sortedDirs) for _, d := range sortedDirs { if err := writeTarDir(tw, d); err != nil { return nil, xerrors.Errorf("write dir %s to tar: %w", d, err) } } for _, name := range names { if err := writeTarFile(tw, name, result.ExtraFiles[name]); err != nil { return nil, xerrors.Errorf("write %s to tar: %w", name, err) } } if err := tw.Close(); err != nil { return nil, xerrors.Errorf("close tar writer: %w", err) } return buf.Bytes(), nil } // writeTarDir adds a directory entry to a tar writer. func writeTarDir(tw *tar.Writer, name string) error { hdr := &tar.Header{ Typeflag: tar.TypeDir, Name: name + "/", Mode: 0o755, ModTime: time.Unix(0, 0), } return tw.WriteHeader(hdr) } // writeTarFile adds a single file entry to a tar writer. It uses a zero // timestamp for reproducible archives. func writeTarFile(tw *tar.Writer, name string, data []byte) error { hdr := &tar.Header{ Name: name, Mode: 0o644, Size: int64(len(data)), ModTime: time.Unix(0, 0), } if err := tw.WriteHeader(hdr); err != nil { return err } _, err := tw.Write(data) return err }