Skip to content

Commit

Permalink
[kpt deployer] Improve skaffold.yaml docs.
Browse files Browse the repository at this point in the history 
* kpt.Dir is required, adding the explanation on the default config.
* kpt.applyDir is removed from top-tier config.
* Rewrote the kpt.Live struct to clarify the config scope and which configs should be considered together.
* Improve the kpt option docstring for skaffold users.
  • Loading branch information
@yuwenma
yuwenma committed Sep 17, 2020
1 parent 2b50012 commit 64f3033
Show file tree
Hide file tree
Showing 4 changed files with 185 additions and 127 deletions.
144 changes: 81 additions & 63 deletions docs/content/en/schemas/v2beta8.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1605,17 +1605,75 @@
"description": "configures Kaniko caching. If a cache is specified, Kaniko will use a remote cache which will speed up builds.",
"x-intellij-html-description": "configures Kaniko caching. If a cache is specified, Kaniko will use a remote cache which will speed up builds."
},
"KptDeploy": {
"KptApplyInventory": {
"properties": {
"dir": {
"type": "string",
"description": "equivalent to the dir in `kpt live apply <dir>`. If not provided, kpt deployer will create a hidden directory `.kpt-hydrated` to store the manipulated resource output and the kpt inventory-template.yaml file.",
"x-intellij-html-description": "equivalent to the dir in <code>kpt live apply &lt;dir&gt;</code>. If not provided, kpt deployer will create a hidden directory <code>.kpt-hydrated</code> to store the manipulated resource output and the kpt inventory-template.yaml file."
},
"inventoryID": {
"type": "string",
"description": "*alpha* identifier for a group of applied resources. This value is only needed when the `kpt live` is working on a pre-applied cluster resources.",
"x-intellij-html-description": "<em>alpha</em> identifier for a group of applied resources. This value is only needed when the <code>kpt live</code> is working on a pre-applied cluster resources."
},
"inventoryNamespace": {
"type": "string",
"description": "*alpha* sets the inventory namespace.",
"x-intellij-html-description": "<em>alpha</em> sets the inventory namespace."
}
},
"preferredOrder": [
"dir",
"inventoryID",
"inventoryNamespace"
],
"additionalProperties": false,
"description": "sets the kpt inventory directory.",
"x-intellij-html-description": "sets the kpt inventory directory."
},
"KptApplyOptions": {
"properties": {
"applyDir": {
"pollPeriod": {
"type": "string",
"description": "path to the directory to deploy to the cluster.",
"x-intellij-html-description": "path to the directory to deploy to the cluster."
"description": "sets for the polling period for resource statuses. Default to 2s.",
"x-intellij-html-description": "sets for the polling period for resource statuses. Default to 2s."
},
"prunePropagationPolicy": {
"type": "string",
"description": "sets the propagation policy for pruning. Possible settings are Background, Foreground, Orphan. Default to \"Background\".",
"x-intellij-html-description": "sets the propagation policy for pruning. Possible settings are Background, Foreground, Orphan. Default to &quot;Background&quot;."
},
"pruneTimeout": {
"type": "string",
"description": "sets the time threshold to wait for all pruned resources to be deleted.",
"x-intellij-html-description": "sets the time threshold to wait for all pruned resources to be deleted."
},
"reconcileTimeout": {
"type": "string",
"description": "sets the time threshold to wait for all resources to reach the current status.",
"x-intellij-html-description": "sets the time threshold to wait for all resources to reach the current status."
}
},
"preferredOrder": [
"pollPeriod",
"prunePropagationPolicy",
"pruneTimeout",
"reconcileTimeout"
],
"additionalProperties": false,
"description": "adds additional configurations used when calling `kpt live apply`.",
"x-intellij-html-description": "adds additional configurations used when calling <code>kpt live apply</code>."
},
"KptDeploy": {
"required": [
"dir"
],
"properties": {
"dir": {
"type": "string",
"description": "path to the directory to run kpt functions against.",
"x-intellij-html-description": "path to the directory to run kpt functions against."
"description": "path to the config directory (Required). By default, the Dir contains the application configurations, [kustomize config files](https://kubectl.docs.kubernetes.io/pages/examples/kustomize.html) and [declarative kpt functions](https://googlecontainertools.github.io/kpt/guides/consumer/function/#declarative-run).",
"x-intellij-html-description": "path to the config directory (Required). By default, the Dir contains the application configurations, <a href=\"https://kubectl.docs.kubernetes.io/pages/examples/kustomize.html\">kustomize config files</a> and <a href=\"https://googlecontainertools.github.io/kpt/guides/consumer/function/#declarative-run\">declarative kpt functions</a>."
},
"fn": {
"$ref": "#/definitions/KptFn",
Expand All @@ -1629,7 +1687,6 @@
}
},
"preferredOrder": [
"applyDir",
"dir",
"fn",
"live"
Expand All @@ -1642,19 +1699,19 @@
"properties": {
"fnPath": {
"type": "string",
"description": "a directory to read functions from instead of the configuration directory.",
"x-intellij-html-description": "a directory to read functions from instead of the configuration directory."
"description": "directory to discover the declarative kpt functions. If not provided, kpt deployer uses `kpt.Dir`.",
"x-intellij-html-description": "directory to discover the declarative kpt functions. If not provided, kpt deployer uses <code>kpt.Dir</code>."
},
"globalScope": {
"type": "boolean",
"description": "sets global scope for functions.",
"x-intellij-html-description": "sets global scope for functions.",
"description": "sets the global scope for the kpt functions. see `kpt help fn run`.",
"x-intellij-html-description": "sets the global scope for the kpt functions. see <code>kpt help fn run</code>.",
"default": "false"
},
"image": {
"type": "string",
"description": "an image to be run as a function in lieu of running functions from a directory.",
"x-intellij-html-description": "an image to be run as a function in lieu of running functions from a directory."
"description": "a kpt function image to run the configs imperatively. If provided, kpt.fn.fnPath will be ignored.",
"x-intellij-html-description": "a kpt function image to run the configs imperatively. If provided, kpt.fn.fnPath will be ignored."
},
"mount": {
"items": {
Expand All @@ -1667,14 +1724,14 @@
},
"network": {
"type": "boolean",
"description": "enables network access for functions that declare it.",
"x-intellij-html-description": "enables network access for functions that declare it.",
"description": "enables network access for the kpt function containers.",
"x-intellij-html-description": "enables network access for the kpt function containers.",
"default": "false"
},
"networkName": {
"type": "string",
"description": "docker network to run the container in (default \"bridge\").",
"x-intellij-html-description": "docker network to run the container in (default &quot;bridge&quot;)."
"description": "docker network name to run the kpt function containers (default \"bridge\").",
"x-intellij-html-description": "docker network name to run the kpt function containers (default &quot;bridge&quot;)."
}
},
"preferredOrder": [
Expand All @@ -1692,63 +1749,24 @@
"KptLive": {
"properties": {
"apply": {
"$ref": "#/definitions/KptLiveApply",
"$ref": "#/definitions/KptApplyInventory",
"description": "sets the kpt inventory directory.",
"x-intellij-html-description": "sets the kpt inventory directory."
},
"options": {
"$ref": "#/definitions/KptApplyOptions",
"description": "adds additional configurations for `kpt live apply` commands.",
"x-intellij-html-description": "adds additional configurations for <code>kpt live apply</code> commands."
},
"inventoryID": {
"type": "string",
"description": "identifier for a group of applied resources. This configuration is used when users do not specify `KptDeploy.ApplyDir` and `.kpt-hydrated/inventory-template.yaml` does not exist.",
"x-intellij-html-description": "identifier for a group of applied resources. This configuration is used when users do not specify <code>KptDeploy.ApplyDir</code> and <code>.kpt-hydrated/inventory-template.yaml</code> does not exist."
},
"inventoryNamespace": {
"type": "string",
"description": "sets the namespace scope for `kpt live init`.",
"x-intellij-html-description": "sets the namespace scope for <code>kpt live init</code>."
}
},
"preferredOrder": [
"apply",
"inventoryID",
"inventoryNamespace"
"options"
],
"additionalProperties": false,
"description": "adds additional configurations used when calling `kpt live`.",
"x-intellij-html-description": "adds additional configurations used when calling <code>kpt live</code>."
},
"KptLiveApply": {
"properties": {
"pollPeriod": {
"type": "string",
"description": "sets for the polling period for resource statuses. Default to 2s.",
"x-intellij-html-description": "sets for the polling period for resource statuses. Default to 2s."
},
"prunePropagationPolicy": {
"type": "string",
"description": "sets the propagation policy for pruning. Possible settings are Background, Foreground, Orphan. Default to \"Background\".",
"x-intellij-html-description": "sets the propagation policy for pruning. Possible settings are Background, Foreground, Orphan. Default to &quot;Background&quot;."
},
"pruneTimeout": {
"type": "string",
"description": "sets the time threshold to wait for all pruned resources to be deleted.",
"x-intellij-html-description": "sets the time threshold to wait for all pruned resources to be deleted."
},
"reconcileTimeout": {
"type": "string",
"description": "sets the time threshold to wait for all resources to reach the current status.",
"x-intellij-html-description": "sets the time threshold to wait for all resources to reach the current status."
}
},
"preferredOrder": [
"pollPeriod",
"prunePropagationPolicy",
"pruneTimeout",
"reconcileTimeout"
],
"additionalProperties": false,
"description": "adds additional configurations used when calling `kpt live apply`.",
"x-intellij-html-description": "adds additional configurations used when calling <code>kpt live apply</code>."
},
"KubectlDeploy": {
"properties": {
"flags": {
Expand Down
30 changes: 15 additions & 15 deletions pkg/skaffold/deploy/kpt.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,11 +273,11 @@ func (k *KptDeployer) kptFnRun(ctx context.Context) (deploy.ManifestList, error)
// getApplyDir returns the path to applyDir if specified by the user. Otherwise, getApplyDir
// creates a hidden directory named .kpt-hydrated in place of applyDir.
func (k *KptDeployer) getApplyDir(ctx context.Context) (string, error) {
if k.ApplyDir != "" {
if _, err := os.Stat(k.ApplyDir); os.IsNotExist(err) {
if k.Live.Apply.Dir != "" {
if _, err := os.Stat(k.Live.Apply.Dir); os.IsNotExist(err) {
return "", err
}
return k.ApplyDir, nil
return k.Live.Apply.Dir, nil
}

// 0755 is a permission setting where the owner can read, write, and execute.
Expand Down Expand Up @@ -393,20 +393,20 @@ func (k *KptDeployer) getKptFnRunArgs() ([]string, error) {
func (k *KptDeployer) getKptLiveApplyArgs() []string {
var flags []string

if len(k.Live.Apply.PollPeriod) > 0 {
flags = append(flags, "--poll-period", k.Live.Apply.PollPeriod)
if len(k.Live.Options.PollPeriod) > 0 {
flags = append(flags, "--poll-period", k.Live.Options.PollPeriod)
}

if len(k.Live.Apply.PrunePropagationPolicy) > 0 {
flags = append(flags, "--prune-propagation-policy", k.Live.Apply.PrunePropagationPolicy)
if len(k.Live.Options.PrunePropagationPolicy) > 0 {
flags = append(flags, "--prune-propagation-policy", k.Live.Options.PrunePropagationPolicy)
}

if len(k.Live.Apply.PruneTimeout) > 0 {
flags = append(flags, "--prune-timeout", k.Live.Apply.PruneTimeout)
if len(k.Live.Options.PruneTimeout) > 0 {
flags = append(flags, "--prune-timeout", k.Live.Options.PruneTimeout)
}

if len(k.Live.Apply.ReconcileTimeout) > 0 {
flags = append(flags, "--reconcile-timeout", k.Live.Apply.ReconcileTimeout)
if len(k.Live.Options.ReconcileTimeout) > 0 {
flags = append(flags, "--reconcile-timeout", k.Live.Options.ReconcileTimeout)
}

return flags
Expand All @@ -416,12 +416,12 @@ func (k *KptDeployer) getKptLiveApplyArgs() []string {
func (k *KptDeployer) getKptLiveInitArgs() []string {
var flags []string

if len(k.Live.InventoryID) > 0 {
flags = append(flags, "--inventory-id", k.Live.InventoryID)
if len(k.Live.Apply.InventoryID) > 0 {
flags = append(flags, "--inventory-id", k.Live.Apply.InventoryID)
}

if len(k.Live.InventoryNamespace) > 0 {
flags = append(flags, "--namespace", k.Live.InventoryNamespace)
if len(k.Live.Apply.InventoryNamespace) > 0 {
flags = append(flags, "--namespace", k.Live.Apply.InventoryNamespace)
}

return flags
Expand Down
Loading

0 comments on commit 64f3033

Please sign in to comment.