Comment demo functions

Fixes #50

Author: frankfarzan

ts/demo-functions/src/expand_team_cr.ts

@@ -22,17 +22,37 @@ import { RoleBinding, Subject } from './gen/io.k8s.api.rbac.v1';
 const ENVIRONMENTS = ['dev', 'prod'];
 
 export const expandTeamCr: KptFunc = (configs) => {
+  // For each 'Team' custom resource in the input:
+  // 1. Generate a per-enviroment Namespace.
+  // 2. Generate RoleBindings in each Namespace.
   configs.get(isTeam).forEach((team) => {
     const name = team.metadata.name;
 
     ENVIRONMENTS.forEach((suffix) => {
       const ns = `${name}-${suffix}`;
       configs.insert(Namespace.named(ns));
-      configs.insert(...expandTeam(team, ns));
+      configs.insert(...createRoleBindings(team, ns));
     });
   });
 };
 
+function createRoleBindings(team: Team, namespace: string): RoleBinding[] {
+  return (team.spec.roles || []).map((item) => {
+    return new RoleBinding({
+      metadata: {
+        name: item.role,
+        namespace,
+      },
+      subjects: roleSubjects(item),
+      roleRef: {
+        kind: 'ClusterRole',
+        name: item.role,
+        apiGroup: 'rbac.authorization.k8s.io',
+      },
+    });
+  });
+}
+
 function roleSubjects(item: Team.Spec.Item): Subject[] {
   const userSubjects: Subject[] = (item.users || []).map(
     (user) =>
@@ -51,23 +71,6 @@ function roleSubjects(item: Team.Spec.Item): Subject[] {
   return userSubjects.concat(groupSubjects);
 }
 
-function expandTeam(team: Team, namespace: string): RoleBinding[] {
-  return (team.spec.roles || []).map((item) => {
-    return new RoleBinding({
-      metadata: {
-        name: item.role,
-        namespace,
-      },
-      subjects: roleSubjects(item),
-      roleRef: {
-        kind: 'ClusterRole',
-        name: item.role,
-        apiGroup: 'rbac.authorization.k8s.io',
-      },
-    });
-  });
-}
-
 expandTeamCr.usage = `
 Generates per-environment Namespaces and RoleBindings from the 'Team' custom resource.
 

ts/demo-functions/src/mutate_psp.ts

@@ -18,6 +18,8 @@ import { KptFunc } from '@googlecontainertools/kpt-functions';
 import { isPodSecurityPolicy } from './gen/io.k8s.api.policy.v1beta1';
 
 export const mutatePsp: KptFunc = (configs) => {
+  // Iterate over all PodSecurityPolicy objects in the input and if
+  // the 'allowPrivilegeEscalation' field is not to 'false', set the field to false.
   configs
     .get(isPodSecurityPolicy)
     .filter((psp) => psp.spec && psp.spec.allowPrivilegeEscalation !== false)

ts/demo-functions/src/read_yaml.ts

@@ -24,13 +24,17 @@ export const SOURCE_DIR = 'source_dir';
 export const FILTER_IVNALID = 'filter_invalid';
 
 export const readYaml: kpt.KptFunc = (configs) => {
+  // Get the parameters.
   const sourceDir = configs.getFunctionConfigValueOrThrow(SOURCE_DIR);
   const ignoreInvalid = configs.getFunctionConfigValue(FILTER_IVNALID) === 'true';
 
   // Discard any input objects since this is a source function.
   configs.deleteAll();
 
+  // Only read files with YAML extensions. Other file types are ignored.
   const files = glob.sync(sourceDir + '/**/*.+(yaml|yml)');
+
+  // Parse each file and convert it to a KubernetesObject.
   const errors: kpt.ConfigError[] = files
     .map((f) => parseFile(configs, sourceDir, f, ignoreInvalid))
     .filter((err) => err !== undefined)
@@ -72,6 +76,7 @@ function parseFile(
   const contents = readFileOrThrow(file);
   let objects = safeLoadAll(contents);
 
+  // Filter for objects that are not KubernetesObject. This is conditional on 'ignoreValid' parameter.
   const invalidObjects: object[] = objects.filter((o) => !kpt.isKubernetesObject(o));
   if (invalidObjects.length) {
     if (ignoreInvalid) {
@@ -84,10 +89,13 @@ function parseFile(
     }
   }
 
+  // Add the standard path and index annotations to preserve the filesystem hierarchy
+  // and ordering within a file.
   objects.forEach((o, i) => {
     kpt.addAnnotation(o, kpt.SOURCE_PATH_ANNOTATION, path.relative(sourceDir, file));
     kpt.addAnnotation(o, kpt.SOURCE_INDEX_ANNOTATION, i.toString());
   });
+
   configs.insert(...objects);
   return;
 }

ts/demo-functions/src/validate_rolebinding.ts

@@ -24,8 +24,11 @@ import { isRoleBinding } from './gen/io.k8s.api.rbac.v1';
 export const SUBJECT_NAME = 'subject_name';
 
 export const validateRolebinding: KptFunc = (configs) => {
+  // Get the subject name parameter.
   const subjectName = configs.getFunctionConfigValueOrThrow(SUBJECT_NAME);
 
+  // Iterate over all RoleBinding objects in the input, and filter those that have a subject
+  // we're looking for.
   let errors: KubernetesObjectError[] = configs
     .get(isRoleBinding)
     .filter((rb) => rb && rb.subjects && rb.subjects.find((s) => s.name === subjectName))

ts/demo-functions/src/write_yaml.ts

@@ -33,17 +33,22 @@ const YAML_STYLE: DumpOptions = {
 };
 
 export const writeYaml: kpt.KptFunc = (configs) => {
+  // Get the paramters.
   const sinkDir = configs.getFunctionConfigValueOrThrow(SINK_DIR);
   const overwrite = configs.getFunctionConfigValue(OVERWRITE) === 'true';
 
+  // If sink diretory is not empty, require 'overwrite' parameter to be set.
   const yamls = listYamlFiles(sinkDir);
   if (!overwrite && yamls.length > 0) {
     throw new Error(`sink dir contains YAML files and overwrite is not set to string 'true'.`);
   }
 
   const filesToDelete = new Set(yamls);
 
+  // Group objects by the file path and create a multi-object file if required.
   configs.groupBy(buildSourcePath).forEach(([p, configsAtPath]) => {
+    // Preserve the original filesystem hierarchy and object ordering using the annotations
+    // set by the source function. Remove these annotations before writing files.
     const documents = configsAtPath
       .sort(compareSourceIndex)
       .map((config) => kpt.removeAnnotation(config, kpt.SOURCE_INDEX_ANNOTATION))
@@ -59,7 +64,6 @@ export const writeYaml: kpt.KptFunc = (configs) => {
 
     if (fs.existsSync(file)) {
       filesToDelete.delete(file);
-      // Doesn't handle large files well. Should compare buffered output.
       const currentContents = fs.readFileSync(file).toString();
       if (contents == currentContents) {
         // No changes to make.
@@ -70,6 +74,8 @@ export const writeYaml: kpt.KptFunc = (configs) => {
     fs.writeFileSync(file, contents, 'utf8');
   });
 
+  // Delete YAML files that are missing from the input.
+  // Other file types are ignored.
   filesToDelete.forEach((file) => {
     fs.unlinkSync(file);
   });