From 06a1249e9002627c722bbe932933f53ea9ff5d57 Mon Sep 17 00:00:00 2001 From: balopat Date: Fri, 1 Nov 2019 16:40:00 -0700 Subject: [PATCH 01/11] control api + swagger ui for http api --- docs/content/en/api/skaffold.swagger.json | 382 ++++++ docs/content/en/docs/design/api.md | 87 +- docs/content/en/docs/references/_index.md | 5 +- .../{deprecation/_index.md => deprecation.md} | 4 +- .../references/{api/_index.md => grpc.md} | 217 ++-- .../{privacy/_index.md => privacy.md} | 4 +- docs/content/en/docs/references/swagger.md | 50 + .../en/docs/references/yaml/_index.html | 2 +- docs/layouts/partials/footer.html | 2 +- docs/layouts/partials/hooks/head-end.html | 2 + docs/static/scripts/ie8.polyfils.map | 1 + docs/static/scripts/ie8.polyfils.min.js | 4 + .../scripts/iframeResizer.contentWindow.js | 1108 +++++++++++++++++ .../scripts/iframeResizer.contentWindow.map | 1 + .../iframeResizer.contentWindow.min.js | 10 + docs/static/scripts/iframeResizer.js | 1002 +++++++++++++++ docs/static/scripts/iframeResizer.map | 1 + docs/static/scripts/iframeResizer.min.js | 9 + docs/static/scripts/index.js | 2 + docs/static/stylesheets/colors.css | 6 +- docs/static/swagger/custom.css | 3 + docs/static/swagger/favicon-16x16.png | Bin 0 -> 665 bytes docs/static/swagger/favicon-32x32.png | Bin 0 -> 628 bytes docs/static/swagger/swagger-ui-bundle.js | 134 ++ docs/static/swagger/swagger-ui-bundle.js.map | 1 + .../swagger/swagger-ui-standalone-preset.js | 22 + .../swagger-ui-standalone-preset.js.map | 1 + docs/static/swagger/swagger-ui.css | 4 + docs/static/swagger/swagger-ui.css.map | 1 + docs/static/swagger/swagger-ui.js | 9 + docs/static/swagger/swagger-ui.js.map | 1 + hack/generate-man.sh | 2 +- hack/generate-proto.sh | 3 +- hack/proto/Dockerfile | 4 +- hack/test-generated-proto.sh | 2 +- integration/dev_test.go | 4 +- integration/rpc_test.go | 2 +- pkg/skaffold/server/endpoints.go | 11 +- proto/markdown.tmpl | 97 ++ proto/skaffold.pb.go | 281 ++--- proto/skaffold.pb.gw.go | 156 +-- proto/skaffold.proto | 147 ++- 42 files changed, 3196 insertions(+), 588 deletions(-) create mode 100644 docs/content/en/api/skaffold.swagger.json rename docs/content/en/docs/references/{deprecation/_index.md => deprecation.md} (99%) rename docs/content/en/docs/references/{api/_index.md => grpc.md} (64%) rename docs/content/en/docs/references/{privacy/_index.md => privacy.md} (97%) create mode 100644 docs/content/en/docs/references/swagger.md create mode 100755 docs/static/scripts/ie8.polyfils.map create mode 100755 docs/static/scripts/ie8.polyfils.min.js create mode 100755 docs/static/scripts/iframeResizer.contentWindow.js create mode 100755 docs/static/scripts/iframeResizer.contentWindow.map create mode 100755 docs/static/scripts/iframeResizer.contentWindow.min.js create mode 100755 docs/static/scripts/iframeResizer.js create mode 100755 docs/static/scripts/iframeResizer.map create mode 100755 docs/static/scripts/iframeResizer.min.js create mode 100755 docs/static/scripts/index.js create mode 100644 docs/static/swagger/custom.css create mode 100644 docs/static/swagger/favicon-16x16.png create mode 100644 docs/static/swagger/favicon-32x32.png create mode 100644 docs/static/swagger/swagger-ui-bundle.js create mode 100644 docs/static/swagger/swagger-ui-bundle.js.map create mode 100644 docs/static/swagger/swagger-ui-standalone-preset.js create mode 100644 docs/static/swagger/swagger-ui-standalone-preset.js.map create mode 100644 docs/static/swagger/swagger-ui.css create mode 100644 docs/static/swagger/swagger-ui.css.map create mode 100644 docs/static/swagger/swagger-ui.js create mode 100644 docs/static/swagger/swagger-ui.js.map create mode 100644 proto/markdown.tmpl diff --git a/docs/content/en/api/skaffold.swagger.json b/docs/content/en/api/skaffold.swagger.json new file mode 100644 index 00000000000..fa828c2c104 --- /dev/null +++ b/docs/content/en/api/skaffold.swagger.json @@ -0,0 +1,382 @@ +{ + "swagger": "2.0", + "info": { + "title": "skaffold.proto", + "version": "version not set" + }, + "schemes": [ + "http", + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/v1/event_log": { + "get": { + "summary": "EventLog returns all the events of the current Skaffold execution from the start", + "operationId": "EventLog", + "responses": { + "200": { + "description": "A successful response.(streaming responses)", + "schema": { + "$ref": "#/x-stream-definitions/protoLogEntry" + } + } + }, + "tags": [ + "SkaffoldService" + ] + } + }, + "/v1/execute": { + "post": { + "summary": "Execute allows for a single execution of some or all of the phases (build, sync, deploy) in case autoBuild, autoDeploy or autoSync are disabled.", + "operationId": "Execute", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "properties": {} + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/protoIntent" + } + } + ], + "tags": [ + "SkaffoldService" + ] + } + }, + "/v1/state": { + "get": { + "summary": "GetState returns the state of the current Skaffold execution", + "operationId": "GetState", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/protoState" + } + } + }, + "tags": [ + "SkaffoldService" + ] + } + } + }, + "definitions": { + "protoBuildEvent": { + "type": "object", + "properties": { + "artifact": { + "type": "string" + }, + "status": { + "type": "string" + }, + "err": { + "type": "string" + } + }, + "description": "BuildEvent describes the build status per artifact, and will be emitted by Skaffold anytime a build starts or finishes, successfully or not.\nIf the build fails, an error will be attached to the event." + }, + "protoBuildState": { + "type": "object", + "properties": { + "artifacts": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "title": "BuildState contains a map of all skaffold artifacts to their current build\nstates" + }, + "protoDeployEvent": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "err": { + "type": "string" + } + }, + "description": "DeployEvent gives the status of a deployment, and will be emitted by Skaffold\nanytime a deployment starts or completes, successfully or not." + }, + "protoDeployState": { + "type": "object", + "properties": { + "status": { + "type": "string" + } + }, + "title": "DeployState contains the status of the current deploy" + }, + "protoEvent": { + "type": "object", + "properties": { + "metaEvent": { + "$ref": "#/definitions/protoMetaEvent" + }, + "buildEvent": { + "$ref": "#/definitions/protoBuildEvent" + }, + "deployEvent": { + "$ref": "#/definitions/protoDeployEvent" + }, + "portEvent": { + "$ref": "#/definitions/protoPortEvent" + }, + "statusCheckEvent": { + "$ref": "#/definitions/protoStatusCheckEvent" + }, + "resourceStatusCheckEvent": { + "$ref": "#/definitions/protoResourceStatusCheckEvent" + }, + "fileSyncEvent": { + "$ref": "#/definitions/protoFileSyncEvent" + } + }, + "description": "Event is one of the following events." + }, + "protoFileSyncEvent": { + "type": "object", + "properties": { + "fileCount": { + "type": "integer", + "format": "int32" + }, + "image": { + "type": "string" + }, + "status": { + "type": "string" + }, + "err": { + "type": "string" + } + }, + "description": "FileSyncEvent describes the sync status." + }, + "protoFileSyncState": { + "type": "object", + "properties": { + "status": { + "type": "string" + } + }, + "title": "FileSyncState contains the status of the current file sync" + }, + "protoIntent": { + "type": "object", + "properties": { + "build": { + "type": "boolean", + "format": "boolean" + }, + "sync": { + "type": "boolean", + "format": "boolean" + }, + "deploy": { + "type": "boolean", + "format": "boolean" + } + }, + "description": "Intent represents user intents for a given phase to be unblocked, once." + }, + "protoLogEntry": { + "type": "object", + "properties": { + "timestamp": { + "type": "string", + "format": "date-time" + }, + "event": { + "$ref": "#/definitions/protoEvent" + }, + "entry": { + "type": "string" + } + }, + "description": "LogEntry describes an event and a string description of the event." + }, + "protoMetaEvent": { + "type": "object", + "properties": { + "entry": { + "type": "string" + } + }, + "title": "MetaEvent gives general information regarding Skaffold like version info" + }, + "protoPortEvent": { + "type": "object", + "properties": { + "localPort": { + "type": "integer", + "format": "int32" + }, + "remotePort": { + "type": "integer", + "format": "int32" + }, + "podName": { + "type": "string" + }, + "containerName": { + "type": "string" + }, + "namespace": { + "type": "string" + }, + "portName": { + "type": "string" + }, + "resourceType": { + "type": "string" + }, + "resourceName": { + "type": "string" + } + }, + "description": "PortEvent Event describes each port forwarding event." + }, + "protoResourceStatusCheckEvent": { + "type": "object", + "properties": { + "resource": { + "type": "string" + }, + "status": { + "type": "string" + }, + "message": { + "type": "string" + }, + "err": { + "type": "string" + } + } + }, + "protoState": { + "type": "object", + "properties": { + "buildState": { + "$ref": "#/definitions/protoBuildState" + }, + "deployState": { + "$ref": "#/definitions/protoDeployState" + }, + "forwardedPorts": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/protoPortEvent" + } + }, + "statusCheckState": { + "$ref": "#/definitions/protoStatusCheckState" + }, + "fileSyncState": { + "$ref": "#/definitions/protoFileSyncState" + } + }, + "title": "State represents the current state of the Skaffold components" + }, + "protoStatusCheckEvent": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "message": { + "type": "string" + }, + "err": { + "type": "string" + } + }, + "description": "StatusCheck Event describes if the Status check has started, is in progress, has succeeded or failed." + }, + "protoStatusCheckState": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "resources": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "description": "StatusCheckState contains the state of status check of current deployed resources." + }, + "protobufAny": { + "type": "object", + "properties": { + "type_url": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "runtimeStreamError": { + "type": "object", + "properties": { + "grpc_code": { + "type": "integer", + "format": "int32" + }, + "http_code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "http_status": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + }, + "x-stream-definitions": { + "protoLogEntry": { + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/protoLogEntry" + }, + "error": { + "$ref": "#/definitions/runtimeStreamError" + } + }, + "title": "Stream result of protoLogEntry" + } + } +} diff --git a/docs/content/en/docs/design/api.md b/docs/content/en/docs/design/api.md index 1262aaf9ac7..adc3f77e5b9 100644 --- a/docs/content/en/docs/design/api.md +++ b/docs/content/en/docs/design/api.md @@ -10,11 +10,11 @@ pipeline** and for **controlling the phases in the pipeline**. To retrieve information about the Skaffold pipeline, the Skaffold API provides two main functionalities: - * A [streaming event log]({{< relref "/docs/design/api#events-api">}}) created from the different phases in a pipeline run and + * A [streaming event log]({{< relref "#events-api">}}) created from the different phases in a pipeline run and - * A snapshot of the [overall state]({{< relref "/docs/design/api#state-api" >}}) of the pipeline at any given time during the run. + * A snapshot of the [overall state]({{< relref "#state-api" >}}) of the pipeline at any given time during the run. -To control the individual phases of the Skaffold, the Skaffold API provides [fine grained control over]({{< relref "/docs/design/api#controlling-build-sync-deploy" >}}) +To control the individual phases of the Skaffold, the Skaffold API provides [fine grained control over]({{< relref "#controlling-build-sync-deploy" >}}) the individual phases of the pipeline (build, deploy and sync). @@ -23,7 +23,7 @@ The Skaffold API is `gRPC` based, and it is also exposed via the gRPC gateway as The server is hosted locally on the same host where the skaffold process is running, and will serve by default on ports 50051 and 50052. These ports can be configured through the `--rpc-port` and `--rpc-http-port` flags. -The server's gRPC service definitions and message protos can be found [here]({{< relref "/docs/references/api" >}}). +We generate the server's [gRPC service definitions and message protos]({{< relref "/docs/references/grpc" >}}) as well as the [Swagger based HTTP API Spec]({{< relref "/docs/references/swagger" >}}). ### HTTP server @@ -100,7 +100,7 @@ Example scenarios: | protocol | endpoint | encoding | | ---- | --- | --- | | HTTP | `http://localhost:{HTTP_RPC_PORT}/v1/events` | newline separated JSON using chunk transfer encoding over HTTP| -| gRPC | `client.Events(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/api#skaffoldservice">}}) | protobuf 3 over HTTP | +| gRPC | `client.EventLog(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/grpc#skaffoldservice">}}) | protobuf 3 over HTTP | **Examples** @@ -119,7 +119,7 @@ Using `curl` and `HTTP_RPC_PORT=50052`, an example output of a `skaffold dev` ex ``` {{% /tab %}} {{% tab "gRPC API" %}} -To get events from the `gRPC` server, first create [`gRPC` client]({{< relref "/docs/design/api#creating-a-grpc-client" >}}) +To get events from the `gRPC` server, first create [`gRPC` client]({{< relref "#creating-a-grpc-client" >}}) ```golang func main() { @@ -127,7 +127,7 @@ func main() { defer ctxCancel() // `client` is the gRPC client with connection to localhost:50051. // See code above to create it - logStream, err := client.Events(ctx) + logStream, err := client.EventLog(ctx, &empty.Empty{}) if err != nil { log.Fatalf("could not get events: %v", err) } @@ -146,7 +146,7 @@ func main() { {{% /tab %}} {{% /tabs %}} -Each [Entry log]({{}}) contains an [Event]({{< relref "/docs/references/api#proto.Event" >}}) in the `LogEntry.Event` field and +Each [Entry log]({{}}) contains an [Event]({{< relref "/docs/references/grpc#proto.Event" >}}) in the `LogEntry.Event` field and a string description of the event in `LogEntry.entry` field. @@ -165,7 +165,7 @@ The State API provides a snapshot of the current state of the following componen | protocol | endpoint | encoding | | ---- | --- | --- | | HTTP | `http://localhost:{HTTP_RPC_PORT}/v1/state` | newline separated JSON using chunk transfer encoding over HTTP| -| gRPC | `client.GetState(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/api#skaffoldservice">}}) | protobuf 3 over HTTP | +| gRPC | `client.GetState(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/grpc#skaffoldservice">}}) | protobuf 3 over HTTP | **Examples** @@ -210,7 +210,7 @@ Using `curl` and `HTTP_RPC_PORT=50052`, an example output of a `skaffold dev` ex ``` {{% /tab %}} {{% tab "gRPC API" %}} -To get events over `gRPC` server, first create [`gRPC` client]({{< relref "/docs/design/api#creating-a-grpc-client" >}}) +To get events over `gRPC` server, first create [`gRPC` client]({{< relref "#creating-a-grpc-client" >}}) ```code func main() { // Create a gRPC client connection to localhost:50051. @@ -224,6 +224,69 @@ func main() { {{% /tab %}} {{% /tabs %}} -### Controlling Build/Sync/Deploy +### Control API -TODO: https://github.com/GoogleContainerTools/skaffold/issues/3143 \ No newline at end of file +By default, [`skaffold dev`]({{< relref "/docs/workflows/dev" >}}) automatically builds artifacts, deploys manifests and syncs files on every source code change. +The automation can be turned off with `--auto-build=false` flag for building, `--auto-deploy=false` flag for deploys, and the `--auto-sync=false` flag for file sync. +If automation is turned off for a phase, Skaffold will wait for a call to the Control API before executing the given phase. + +One call to the Control API allows for one execution of the phases specified in the request. +This means that _even if there are new file changes_, Skaffold will wait for another execution request before executing the given phase again. +The Control API mode is best to think about as "semaphores" for build / sync / deploy, that get lifted once per every request. + +**Control API contract** + +| protocol | endpoint | +| ---- | ---- | ---- | +| HTTP, method: POST | `http://localhost:{HTTP_RPC_PORT}/v1/execute`, the [Execution Service]({{}}) | +| gRPC | `client.Execute(ctx)` method on the [`SkaffoldService`]({{< relref "/docs/references/grpc#skaffoldservice">}}) | + + +**Examples** + +{{% tabs %}} +{{% tab "HTTP API" %}} + +Using our [Quickstart example]({{< relref "/docs/quickstart" >}}) we can start skaffold with `skaffold dev --auto-build=false`. +When we change `main.go`, Skaffold will notice file changes but it won't rebuild the image until it receives a call to the Control API with `"build":true`: + +```bash +curl -X POST http://localhost:50052/v1/execute -d '{"build": true}' +``` + +At this point, Skaffold will wait to deploy the newly built image until we invoke the Control API with `"deploy":true`: + +```bash +curl -X POST http://localhost:50052/v1/execute -d '{"deploy": true}' +``` + +Note that you can also combine these steps into one call: + +```bash +curl -X POST http://localhost:50052/v1/execute -d '{"build": true, "deploy": true}' +``` + +{{% /tab %}} +{{% tab "gRPC API" %}} +To get events from the `gRPC` server, first create [`gRPC` client]({{< relref "#creating-a-grpc-client" >}}) + +```golang +func main() { + ctx, ctxCancel := context.WithCancel(context.Background()) + defer ctxCancel() + // `client` is the gRPC client with connection to localhost:50051. + // See code above to create it + _, err = client.Execute(ctx, &pb.UserIntentRequest{ + Intent: &pb.Intent{ + Build: true, + Sync: true, + Deploy: true, + }, + }) + if err != nil { + log.Fatalf("error when trying to execute phases: %v", err) + } +} +``` +{{% /tab %}} +{{% /tabs %}} diff --git a/docs/content/en/docs/references/_index.md b/docs/content/en/docs/references/_index.md index 17a3e7e9af2..e582b22ee8e 100755 --- a/docs/content/en/docs/references/_index.md +++ b/docs/content/en/docs/references/_index.md @@ -8,7 +8,8 @@ weight: 100 |----------| | [CLI]({{< relref "/docs/references/cli" >}}) | | [skaffold.yaml]({{< relref "/docs/references/yaml" >}}) | -| [Deprecation Policy]({{< relref "/docs/references/deprecation" >}}) | +| [gRPC API]({{< relref "/docs/references/grpc" >}}) | +| [HTTP API]({{< relref "/docs/references/swagger" >}}) | | [Privacy Settings] ({{< relref "/docs/references/privacy" >}}) | -| [API Reference]({{< relref "/docs/references/api" >}}) | +| [Deprecation Policy]({{< relref "/docs/references/deprecation" >}}) | diff --git a/docs/content/en/docs/references/deprecation/_index.md b/docs/content/en/docs/references/deprecation.md similarity index 99% rename from docs/content/en/docs/references/deprecation/_index.md rename to docs/content/en/docs/references/deprecation.md index e780049d3ae..b04b59fa70d 100644 --- a/docs/content/en/docs/references/deprecation/_index.md +++ b/docs/content/en/docs/references/deprecation.md @@ -1,7 +1,7 @@ --- title: "Deprecation Policy" linkTitle: "Deprecation policy" -weight: 300 +weight: 60 --- # Skaffold deprecation policy @@ -126,4 +126,4 @@ This flag will will be removed earliest 06/15/2019. - `DIGEST_ALGO` - `DIGEST_HEX` Currently these variables resolve to `_DEPRECATED__`, and the new tagging mechanism adds a digest to the image name thus it shouldn't break existing configurations. -This backward compatibility behavior will be removed earliest 05/14/2019. \ No newline at end of file +This backward compatibility behavior will be removed earliest 05/14/2019. diff --git a/docs/content/en/docs/references/api/_index.md b/docs/content/en/docs/references/grpc.md similarity index 64% rename from docs/content/en/docs/references/api/_index.md rename to docs/content/en/docs/references/grpc.md index 6c00678b902..d6079e9b41e 100644 --- a/docs/content/en/docs/references/api/_index.md +++ b/docs/content/en/docs/references/grpc.md @@ -1,51 +1,54 @@ -# Protocol Documentation - - -## Table of Contents - -- [skaffold.proto](#skaffold.proto) - - [BuildEvent](#proto.BuildEvent) - - [BuildState](#proto.BuildState) - - [BuildState.ArtifactsEntry](#proto.BuildState.ArtifactsEntry) - - [DeployEvent](#proto.DeployEvent) - - [DeployState](#proto.DeployState) - - [Event](#proto.Event) - - [FileSyncEvent](#proto.FileSyncEvent) - - [FileSyncState](#proto.FileSyncState) - - [Intent](#proto.Intent) - - [LogEntry](#proto.LogEntry) - - [MetaEvent](#proto.MetaEvent) - - [PortEvent](#proto.PortEvent) - - [Request](#proto.Request) - - [ResourceStatusCheckEvent](#proto.ResourceStatusCheckEvent) - - [Response](#proto.Response) - - [State](#proto.State) - - [State.ForwardedPortsEntry](#proto.State.ForwardedPortsEntry) - - [StateResponse](#proto.StateResponse) - - [StatusCheckEvent](#proto.StatusCheckEvent) - - [StatusCheckState](#proto.StatusCheckState) - - [StatusCheckState.ResourcesEntry](#proto.StatusCheckState.ResourcesEntry) - - [UserIntentRequest](#proto.UserIntentRequest) - - - - - [SkaffoldService](#proto.SkaffoldService) - - -- [Scalar Value Types](#scalar-value-types) +--- +title: "gRPC API" +linkTitle: "gRPC API" +weight: 30 +--- + +This is a generated reference for the [Skaffold API]({{}}) gRPC layer. + +We also generate the [reference doc for the HTTP layer]({{}}). -

Top

## skaffold.proto +You can find the source for skaffold.proto [on Github](https://github.com/GoogleContainerTools/skaffold/blob/master/proto/skaffold.proto). - -### BuildEvent +### Services + + + +#### SkaffoldService +SkaffoldService describes all the methods for the Skaffold API + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| GetState | [.google.protobuf.Empty](#google.protobuf.Empty) | [State](#proto.State) | GetState returns the state of the current Skaffold execution | +| EventLog | [.google.protobuf.Empty](#google.protobuf.Empty) | [LogEntry](#proto.LogEntry) stream | EventLog returns all the events of the current Skaffold execution from the start | +| Execute | [UserIntentRequest](#proto.UserIntentRequest) | [.google.protobuf.Empty](#google.protobuf.Empty) | Execute allows for a single execution of some or all of the phases (build, sync, deploy) in case autoBuild, autoDeploy or autoSync are disabled. | + + + + +### Data types + + + + +#### BuildEvent BuildEvent describes the build status per artifact, and will be emitted by Skaffold anytime a build starts or finishes, successfully or not. If the build fails, an error will be attached to the event. @@ -61,9 +64,9 @@ If the build fails, an error will be attached to the event. - -### BuildState + +#### BuildState BuildState contains a map of all skaffold artifacts to their current build states @@ -77,9 +80,9 @@ states - -### BuildState.ArtifactsEntry + +#### BuildState.ArtifactsEntry @@ -93,9 +96,9 @@ states - -### DeployEvent + +#### DeployEvent DeployEvent gives the status of a deployment, and will be emitted by Skaffold anytime a deployment starts or completes, successfully or not. @@ -110,9 +113,9 @@ anytime a deployment starts or completes, successfully or not. - -### DeployState + +#### DeployState DeployState contains the status of the current deploy @@ -125,16 +128,16 @@ DeployState contains the status of the current deploy - -### Event + +#### Event Event is one of the following events. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | metaEvent | [MetaEvent](#proto.MetaEvent) | | contains general information regarding Skaffold like version info | -| buildEvent | [BuildEvent](#proto.BuildEvent) | | describes if the build status per artifact. Status could be one of "InProgress", "Completed" or "Failed". | +| buildEvent | [BuildEvent](#proto.BuildEvent) | | describes if the build status per artifact. Status could be one of "InProgress", "Completed" or "Failed". | | deployEvent | [DeployEvent](#proto.DeployEvent) | | describes if the deployment has started, is in progress or is complete. | | portEvent | [PortEvent](#proto.PortEvent) | | describes each port forwarding event. | | statusCheckEvent | [StatusCheckEvent](#proto.StatusCheckEvent) | | describes if the Status check has started, is in progress, has succeeded or failed. | @@ -146,9 +149,9 @@ Event is one of the following events. - -### FileSyncEvent + +#### FileSyncEvent FileSyncEvent describes the sync status. @@ -164,9 +167,9 @@ FileSyncEvent describes the sync status. - -### FileSyncState + +#### FileSyncState FileSyncState contains the status of the current file sync @@ -179,26 +182,26 @@ FileSyncState contains the status of the current file sync - - -### Intent + +#### Intent +Intent represents user intents for a given phase to be unblocked, once. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| build | [bool](#bool) | | | -| sync | [bool](#bool) | | | -| deploy | [bool](#bool) | | | +| build | [bool](#bool) | | in case skaffold dev is ran with autoBuild=false, a build intent enables building once | +| sync | [bool](#bool) | | in case skaffold dev is ran with autoSync=false, a sync intent enables file sync once | +| deploy | [bool](#bool) | | in case skaffold dev is ran with autoDeploy=false, a deploy intent enables deploys once | - -### LogEntry + +#### LogEntry LogEntry describes an event and a string description of the event. @@ -213,9 +216,9 @@ LogEntry describes an event and a string description of the event. - -### MetaEvent + +#### MetaEvent MetaEvent gives general information regarding Skaffold like version info @@ -228,9 +231,9 @@ MetaEvent gives general information regarding Skaffold like version info - -### PortEvent + +#### PortEvent PortEvent Event describes each port forwarding event. @@ -242,7 +245,7 @@ PortEvent Event describes each port forwarding event. | containerName | [string](#string) | | container name if specified in the kubernetes spec | | namespace | [string](#string) | | the namespace of the resource to port forward. | | portName | [string](#string) | | | -| resourceType | [string](#string) | | resource type e.g. "pod", "service". | +| resourceType | [string](#string) | | resource type e.g. "pod", "service". | | resourceName | [string](#string) | | name of the resource to forward. | @@ -250,9 +253,9 @@ PortEvent Event describes each port forwarding event. - -### Request + +#### Request @@ -265,9 +268,9 @@ PortEvent Event describes each port forwarding event. - -### ResourceStatusCheckEvent + +#### ResourceStatusCheckEvent @@ -283,9 +286,9 @@ PortEvent Event describes each port forwarding event. - -### Response + +#### Response @@ -298,9 +301,9 @@ PortEvent Event describes each port forwarding event. - -### State + +#### State State represents the current state of the Skaffold components @@ -317,9 +320,9 @@ State represents the current state of the Skaffold components - -### State.ForwardedPortsEntry + +#### State.ForwardedPortsEntry @@ -333,9 +336,9 @@ State represents the current state of the Skaffold components - -### StateResponse + +#### StateResponse @@ -348,9 +351,9 @@ State represents the current state of the Skaffold components - -### StatusCheckEvent + +#### StatusCheckEvent StatusCheck Event describes if the Status check has started, is in progress, has succeeded or failed. @@ -365,9 +368,9 @@ StatusCheck Event describes if the Status check has started, is in progress, has - -### StatusCheckState + +#### StatusCheckState StatusCheckState contains the state of status check of current deployed resources. @@ -381,9 +384,9 @@ StatusCheckState contains the state of status check of current deployed resource - -### StatusCheckState.ResourcesEntry + +#### StatusCheckState.ResourcesEntry @@ -397,9 +400,9 @@ StatusCheckState contains the state of status check of current deployed resource - -### UserIntentRequest + +#### UserIntentRequest @@ -411,47 +414,11 @@ StatusCheckState contains the state of status check of current deployed resource - - - - - + + - - -### SkaffoldService + -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ------------| -| GetState | [.google.protobuf.Empty](#google.protobuf.Empty) | [State](#proto.State) | | -| EventLog | [LogEntry](#proto.LogEntry) stream | [LogEntry](#proto.LogEntry) stream | | -| Events | [LogEntry](#proto.LogEntry) stream | [LogEntry](#proto.LogEntry) stream | | -| Handle | [Event](#proto.Event) | [.google.protobuf.Empty](#google.protobuf.Empty) | | -| Execute | [UserIntentRequest](#proto.UserIntentRequest) | [.google.protobuf.Empty](#google.protobuf.Empty) | | - - - - - -## Scalar Value Types - -| .proto Type | Notes | C++ Type | Java Type | Python Type | -| ----------- | ----- | -------- | --------- | ----------- | -| double | | double | double | float | -| float | | float | float | float | -| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | -| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | -| uint32 | Uses variable-length encoding. | uint32 | int | int/long | -| uint64 | Uses variable-length encoding. | uint64 | long | int/long | -| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | -| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | -| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | -| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | -| sfixed32 | Always four bytes. | int32 | int | int | -| sfixed64 | Always eight bytes. | int64 | long | int/long | -| bool | | bool | boolean | boolean | -| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | -| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | diff --git a/docs/content/en/docs/references/privacy/_index.md b/docs/content/en/docs/references/privacy.md similarity index 97% rename from docs/content/en/docs/references/privacy/_index.md rename to docs/content/en/docs/references/privacy.md index 850532a4f04..ca9a0d6fc2d 100644 --- a/docs/content/en/docs/references/privacy/_index.md +++ b/docs/content/en/docs/references/privacy.md @@ -1,7 +1,7 @@ --- title: "Privacy Settings" linkTitle: "Privacy Settings" -weight: 300 +weight: 50 --- The privacy of our users is very important to us. @@ -18,4 +18,4 @@ To disable the update check you have two options: 2. turn it off in skaffold's global config with: ```bash skaffold config set -g update-check false -``` \ No newline at end of file +``` diff --git a/docs/content/en/docs/references/swagger.md b/docs/content/en/docs/references/swagger.md new file mode 100644 index 00000000000..8069ec8ea2e --- /dev/null +++ b/docs/content/en/docs/references/swagger.md @@ -0,0 +1,50 @@ +--- +title: "HTTP API" +linkTitle: "HTTP API" +weight: 40 +--- + +This is a generated reference for the [Skaffold API]({{}}) HTTP layer. + +We also generate the [reference doc for the gRPC layer]({{}}). + + +
+ + + + + diff --git a/docs/content/en/docs/references/yaml/_index.html b/docs/content/en/docs/references/yaml/_index.html index 2a35cae0ad0..55451fb2263 100755 --- a/docs/content/en/docs/references/yaml/_index.html +++ b/docs/content/en/docs/references/yaml/_index.html @@ -1,7 +1,7 @@ --- title: "skaffold.yaml" linkTitle: "skaffold.yaml" -weight: 120 +weight: 20 --- diff --git a/docs/layouts/partials/footer.html b/docs/layouts/partials/footer.html index 64b0cf37521..ba7e0551743 100644 --- a/docs/layouts/partials/footer.html +++ b/docs/layouts/partials/footer.html @@ -1,5 +1,5 @@ {{ $links := .Site.Params.links }} -