From f02d70cab6bae5349e376df8f6850086eeca34a0 Mon Sep 17 00:00:00 2001 From: David Gageot Date: Fri, 8 Feb 2019 13:20:50 +0100 Subject: [PATCH] Add more comments to the Config structs Signed-off-by: David Gageot --- pkg/skaffold/schema/latest/config.go | 377 +++++++++++++++++++++------ 1 file changed, 299 insertions(+), 78 deletions(-) diff --git a/pkg/skaffold/schema/latest/config.go b/pkg/skaffold/schema/latest/config.go index c727897a849..a1e89acc52c 100644 --- a/pkg/skaffold/schema/latest/config.go +++ b/pkg/skaffold/schema/latest/config.go @@ -32,29 +32,66 @@ type SkaffoldPipeline struct { APIVersion string `yaml:"apiVersion"` Kind string `yaml:"kind"` - Build BuildConfig `yaml:"build,omitempty"` - Test TestConfig `yaml:"test,omitempty"` - Deploy DeployConfig `yaml:"deploy,omitempty"` - Profiles []Profile `yaml:"profiles,omitempty"` + // Build describes how images are built. + // **Required** + Build BuildConfig `yaml:"build,omitempty"` + + // Test describes how images are tested. + Test TestConfig `yaml:"test,omitempty"` + + // Deploy describes how images are deployed. + Deploy DeployConfig `yaml:"deploy,omitempty"` + + // Profiles (beta) has all the information which can be used to override any build, + // test or deploy configuration. + // The type of the deployment method can be `kubectl` (beta), `helm` (beta) or `kustomize` (beta). + Profiles []Profile `yaml:"profiles,omitempty"` } func (c *SkaffoldPipeline) GetVersion() string { return c.APIVersion } -// BuildConfig contains all the configuration for the build steps +// BuildConfig contains all the configuration for the build steps. type BuildConfig struct { + // Artifacts lists the images you're going to be building. + // You can include as many as you want here. Artifacts []*Artifact `yaml:"artifacts,omitempty"` - TagPolicy TagPolicy `yaml:"tagPolicy,omitempty"` + + // TagPolicy (beta) determines how Skaffold is going to tag images. + // We provide a few strategies here, although you most likely won't need to care! + // The policy can be `gitCommit` (beta), `sha256` (beta), `envTemplate` (beta) or `dateTime` (beta). + // If not specified, it defaults to `gitCommit: {}`. + TagPolicy TagPolicy `yaml:"tagPolicy,omitempty"` + BuildType `yaml:",inline"` } // TagPolicy contains all the configuration for the tagging step type TagPolicy struct { - GitTagger *GitTagger `yaml:"gitCommit,omitempty" yamltags:"oneOf=tag"` - ShaTagger *ShaTagger `yaml:"sha256,omitempty" yamltags:"oneOf=tag"` + // GitTagger tags images with the git tag or git commit of the artifact workspace directory. + GitTagger *GitTagger `yaml:"gitCommit,omitempty" yamltags:"oneOf=tag"` + + // ShaTagger tags images with their sha256 digest. + ShaTagger *ShaTagger `yaml:"sha256,omitempty" yamltags:"oneOf=tag"` + + // EnvTemplateTagger tags images with a configurable template string. + // The template must be in the golang text/template syntax: https://golang.org/pkg/text/template/ + // The template is compiled and executed against the current environment, + // with those variables injected: + // IMAGE_NAME | Name of the image being built, as supplied in the artifacts section. + // For example: "{{.RELEASE}}-{{.IMAGE_NAME}}" EnvTemplateTagger *EnvTemplateTagger `yaml:"envTemplate,omitempty" yamltags:"oneOf=tag"` - DateTimeTagger *DateTimeTagger `yaml:"dateTime,omitempty" yamltags:"oneOf=tag"` + + // DateTimeTagger tags images with the build timestamp. + // The format can be overridden with golang formats, see: https://golang.org/pkg/time/#Time.Format + // Default format is "2006-01-02_15-04-05.999_MST + // The timezone is by default the local timezone, this can be overridden, see https://golang.org/pkg/time/#Time.LoadLocation + // For example: + // dateTime: + // format: "2006-01-02" + // timezone: "UTC" + DateTimeTagger *DateTimeTagger `yaml:"dateTime,omitempty" yamltags:"oneOf=tag"` } // ShaTagger contains the configuration for the SHA tagger. @@ -77,28 +114,75 @@ type DateTimeTagger struct { // BuildType contains the specific implementation and parameters needed // for the build step. Only one field should be populated. type BuildType struct { - LocalBuild *LocalBuild `yaml:"local,omitempty" yamltags:"oneOf=build"` + // LocalBuild describes how to do a build on the local docker daemon + // and optionally push to a repository. + LocalBuild *LocalBuild `yaml:"local,omitempty" yamltags:"oneOf=build"` + + // GoogleCloudBuild describes how to do a remote build on Google Cloud Build. GoogleCloudBuild *GoogleCloudBuild `yaml:"googleCloudBuild,omitempty" yamltags:"oneOf=build"` - KanikoBuild *KanikoBuild `yaml:"kaniko,omitempty" yamltags:"oneOf=build"` + + // KanikoBuild describes how to do an on-cluster build using + // the kaniko image. + KanikoBuild *KanikoBuild `yaml:"kaniko,omitempty" yamltags:"oneOf=build"` } -// LocalBuild contains the fields needed to do a build on the local docker daemon +// LocalBuild describes how to do a build on the local docker daemon // and optionally push to a repository. type LocalBuild struct { - Push *bool `yaml:"push,omitempty"` - UseDockerCLI bool `yaml:"useDockerCLI,omitempty"` - UseBuildkit bool `yaml:"useBuildkit,omitempty"` + // Push should images be pushed to a registry. + // Default: `false` for local clusters, `true` for remote clusters. + Push *bool `yaml:"push,omitempty"` + + // UseDockerCLI use `docker` command-line interface instead of Docker Engine APIs. + UseDockerCLI bool `yaml:"useDockerCLI,omitempty"` + + // UseBuildkit use BuildKit to build Docker images. + UseBuildkit bool `yaml:"useBuildkit,omitempty"` } -// GoogleCloudBuild contains the fields needed to do a remote build on -// Google Cloud Build. +// GoogleCloudBuild describes how to do a remote build on +// [Google Cloud Build](https://cloud.google.com/cloud-build/docs/). +// Docker and Jib artifacts can be built on Cloud Build. The `projectId` needs +// to be provided and the currently logged in user should be given permissions to trigger +// new builds. type GoogleCloudBuild struct { - ProjectID string `yaml:"projectId,omitempty"` - DiskSizeGb int64 `yaml:"diskSizeGb,omitempty"` + // ProjectID the ID of your Google Cloud Platform Project. + // If the projectId is not provided, Skaffold will guess it from the image name. + // For example, if the artifact image name is `gcr.io/myproject/image`, then Skaffold + // will use the `myproject` GCP project. + ProjectID string `yaml:"projectId,omitempty"` + + // DiskSizeGb the disk size of the VM that runs the build. + // See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) + // for more information. + DiskSizeGb int64 `yaml:"diskSizeGb,omitempty"` + + // MachineType the type of the VM that runs the build. + // See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) + // for more information. MachineType string `yaml:"machineType,omitempty"` - Timeout string `yaml:"timeout,omitempty"` + + // Timeout the amount of time (in seconds) that this build should be allowed to run. + // See [Cloud Build API Reference: Resource/Build](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#resource-build) + // for more information. + Timeout string `yaml:"timeout,omitempty"` + + // DockerImage the name of the image that will run a docker build. + // See [Cloud Builders](https://cloud.google.com/cloud-build/docs/cloud-builders) + // for more information. + // Defaults to `gcr.io/cloud-builders/docker`. DockerImage string `yaml:"dockerImage,omitempty"` - MavenImage string `yaml:"mavenImage,omitempty"` + + // MavenImage the name of the image that will run a maven build. + // See [Cloud Builders](https://cloud.google.com/cloud-build/docs/cloud-builders) + // for more information. + // Defaults to `gcr.io/cloud-builders/mvn`. + MavenImage string `yaml:"mavenImage,omitempty"` + + // GradleImage the name of the image that will run a gradle build. + // See [Cloud Builders](https://cloud.google.com/cloud-build/docs/cloud-builders) + // for more information. + // Defaults to `gcr.io/cloud-builders/gradle`. GradleImage string `yaml:"gradleImage,omitempty"` } @@ -118,23 +202,47 @@ type KanikoCache struct { Repo string `yaml:"repo,omitempty"` } -// KanikoBuild contains the fields needed to do a on-cluster build using -// the kaniko image +// KanikoBuild describes how to do a on-cluster build using the kaniko image. type KanikoBuild struct { - BuildContext *KanikoBuildContext `yaml:"buildContext,omitempty"` - Cache *KanikoCache `yaml:"cache,omitempty"` - AdditionalFlags []string `yaml:"flags,omitempty"` - PullSecret string `yaml:"pullSecret,omitempty"` - PullSecretName string `yaml:"pullSecretName,omitempty"` - Namespace string `yaml:"namespace,omitempty"` - Timeout string `yaml:"timeout,omitempty"` - Image string `yaml:"image,omitempty"` - DockerConfig *DockerConfig `yaml:"dockerConfig,omitempty"` + // BuildContext the Kaniko build context: `gcsBucket` or `localDir`. + // Defaults to `localDir`. + BuildContext *KanikoBuildContext `yaml:"buildContext,omitempty"` + + Cache *KanikoCache `yaml:"cache,omitempty"` + + AdditionalFlags []string `yaml:"flags,omitempty"` + + // PullSecret the path to the secret key file. + // See [Kaniko Documentation: Running Kaniko in a Kubernetes cluster](https://github.com/GoogleContainerTools/kaniko#running-kaniko-in-a-kubernetes-cluster) + // for more information. + PullSecret string `yaml:"pullSecret,omitempty"` + + // PullSecretName the name of the Kubernetes secret for pulling the files + // from the build context and pushing the final image. + // Defaults to `kaniko-secret`. + PullSecretName string `yaml:"pullSecretName,omitempty"` + + // Namespace the Kubernetes namespace. + // Defaults to current namespace in Kubernetes configuration. + Namespace string `yaml:"namespace,omitempty"` + + // Timeout the amount of time (in seconds) that this build should be allowed to run. + // Defaults to 20 minutes (`20m`). + Timeout string `yaml:"timeout,omitempty"` + + // Image used bu the Kaniko pod. + // Defaults to the latest released version of `gcr.io/kaniko-project/executor` + Image string `yaml:"image,omitempty"` + + // DockerConfig + DockerConfig *DockerConfig `yaml:"dockerConfig,omitempty"` } // DockerConfig contains information about the docker config.json to mount type DockerConfig struct { - Path string `yaml:"path,omitempty"` + // Path path to the docker `config.json` + Path string `yaml:"path,omitempty"` + SecretName string `yaml:"secretName,omitempty"` } @@ -155,16 +263,26 @@ type DeployConfig struct { // DeployType contains the specific implementation and parameters needed // for the deploy step. Only one field should be populated. type DeployType struct { - HelmDeploy *HelmDeploy `yaml:"helm,omitempty" yamltags:"oneOf=deploy"` - KubectlDeploy *KubectlDeploy `yaml:"kubectl,omitempty" yamltags:"oneOf=deploy"` + HelmDeploy *HelmDeploy `yaml:"helm,omitempty" yamltags:"oneOf=deploy"` + + // KubectlDeploy uses a client side `kubectl apply` to apply the manifests to the cluster. + // You'll need a kubectl CLI version installed that's compatible with your cluster. + KubectlDeploy *KubectlDeploy `yaml:"kubectl,omitempty" yamltags:"oneOf=deploy"` + KustomizeDeploy *KustomizeDeploy `yaml:"kustomize,omitempty" yamltags:"oneOf=deploy"` } // KubectlDeploy contains the configuration needed for deploying with `kubectl apply` type KubectlDeploy struct { - Manifests []string `yaml:"manifests,omitempty"` - RemoteManifests []string `yaml:"remoteManifests,omitempty"` - Flags KubectlFlags `yaml:"flags,omitempty"` + // Manifests lists the Kubernetes yaml or json manifests. + // Defaults to `[\"k8s/*.yaml\"]`. + Manifests []string `yaml:"manifests,omitempty"` + + // RemoteManifests lists Kubernetes Manifests in remote clusters. + RemoteManifests []string `yaml:"remoteManifests,omitempty"` + + // Flags additional flags to pass to `kubectl`. You can specify three types of flags: