diff --git a/docs/content/en/api/skaffold.swagger.json b/docs/content/en/api/skaffold.swagger.json new file mode 100644 index 00000000000..a47a23dc40f --- /dev/null +++ b/docs/content/en/api/skaffold.swagger.json @@ -0,0 +1,599 @@ +{ + "swagger": "2.0", + "info": { + "description": "skaffold.proto", + "version": "version not set" + }, + "schemes": [ + "http", + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/v1/event_log": { + "get": { + "summary": "DEPRECATED. Events should be used instead.\nTODO remove (https://github.com/GoogleContainerTools/skaffold/issues/3168)", + "operationId": "EventLog", + "responses": { + "200": { + "description": "A successful response.(streaming responses)", + "schema": { + "$ref": "#/x-stream-definitions/protoLogEntry" + } + } + }, + "parameters": [ + { + "name": "timestamp", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + }, + { + "name": "event.metaEvent.entry", + "description": "entry, for example: `\"Starting Skaffold: {Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}\"`.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.buildEvent.artifact", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.buildEvent.status", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.buildEvent.err", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.deployEvent.status", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.deployEvent.err", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.portEvent.localPort", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "event.portEvent.remotePort", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "event.portEvent.podName", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.portEvent.containerName", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.portEvent.namespace", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.portEvent.portName", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.portEvent.resourceType", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.portEvent.resourceName", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.statusCheckEvent.status", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.statusCheckEvent.message", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.statusCheckEvent.err", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.resourceStatusCheckEvent.resource", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.resourceStatusCheckEvent.status", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.resourceStatusCheckEvent.message", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.resourceStatusCheckEvent.err", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.fileSyncEvent.fileCount", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "event.fileSyncEvent.image", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.fileSyncEvent.status", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "event.fileSyncEvent.err", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "entry", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "SkaffoldService" + ] + } + }, + "/v1/events": { + "get": { + "summary": "Returns all the events of the current Skaffold execution from the start", + "operationId": "Events", + "responses": { + "200": { + "description": "A successful response.(streaming responses)", + "schema": { + "$ref": "#/x-stream-definitions/protoLogEntry" + } + } + }, + "tags": [ + "SkaffoldService" + ] + } + }, + "/v1/events/handle": { + "post": { + "summary": "EXPERIMENTAL. It allows for custom events to be implemented in custom builders for example.", + "operationId": "Handle", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "properties": {} + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/protoEvent" + } + } + ], + "tags": [ + "SkaffoldService" + ] + } + }, + "/v1/execute": { + "post": { + "summary": "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": "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" + }, + "description": "A map of `artifact name -\u003e build-state`.\nArtifact name is defined in the `skaffold.yaml`.\nThe `build-state` can be: \u003cbr\u003e\n- `\"Not started\"`: not yet started \u003cbr\u003e\n- `\"In progress\"`: build started \u003cbr\u003e\n- `\"Complete\"`: build succeeded \u003cbr\u003e\n- `\"Failed\"`: build failed" + } + }, + "description": "`BuildState` maps Skaffold artifacts to their current build states" + }, + "protoDeployEvent": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "err": { + "type": "string" + } + }, + "description": "`DeployEvent` represents the status of a deployment, and is emitted by Skaffold\nanytime a deployment starts or completes, successfully or not." + }, + "protoDeployState": { + "type": "object", + "properties": { + "status": { + "type": "string" + } + }, + "description": "`DeployState` describes 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` describes an event in the Skaffold process.\nIt is one of MetaEvent, BuildEvent, DeployEvent, PortEvent, StatusCheckEvent, ResourceStatusCheckEvent or FileSyncEvent." + }, + "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" + } + }, + "description": "`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", + "description": "entry, for example: `\"Starting Skaffold: {Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}\"`" + } + }, + "description": "`MetaEvent` provides general information regarding Skaffold" + }, + "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" + } + }, + "description": "A Resource StatusCheck Event, indicates progress for each kubernetes deployment.\nFor every resource, there will be exactly one event with `status` *Succeeded* or *Failed* event.\nThere can be multiple events with `status` *Pending*.\nSkaffold polls for resource status every 0.5 second. If the resource status changes, an event with `status` “Pending”, “Complete” and “Failed”\nwill be sent with the new status." + }, + "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" + } + }, + "description": "`State` represents the current state of the Skaffold components" + }, + "protoStatusCheckEvent": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "message": { + "type": "string" + }, + "err": { + "type": "string" + } + }, + "description": "`StatusCheckEvent` describes if the status check for kubernetes rollout has started, is in progress, has succeeded or failed." + }, + "protoStatusCheckState": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "resources": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "A map of `resource name -\u003e status-check-state`. Where `resource-name` is the kubernetes resource name.\nThe `status-check-state` can be \u003cbr\u003e\n- `\"Not started\"`: indicates that `status-check` has just started. \u003cbr\u003e\n- `\"In progress\"`: InProgress is sent after every resource check is complete. \u003cbr\u003e\n- `\"Succeeded\"`:\n- `\"Failed\"`:" + } + }, + "description": "`StatusCheckState` describes 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" + } + }, + "description": "Stream result of protoLogEntry" + } + } +} diff --git a/docs/content/en/docs/design/api.md b/docs/content/en/docs/design/api.md index 489419a7c2f..0763652caa6 100644 --- a/docs/content/en/docs/design/api.md +++ b/docs/content/en/docs/design/api.md @@ -14,11 +14,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). @@ -27,7 +27,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" >}}). +For reference, we generate the server's [gRPC service definitions and message protos]({{< relref "/docs/references/api/grpc" >}}) as well as the [Swagger based HTTP API Spec]({{< relref "/docs/references/api/swagger" >}}). ### HTTP server @@ -123,7 +123,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 API using `gRPC`, first create a [`gRPC` client]({{< relref "#creating-a-grpc-client" >}}): ```golang func main() { @@ -131,7 +131,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.Events(ctx, &empty.Empty{}) if err != nil { log.Fatalf("could not get events: %v", err) } @@ -150,7 +150,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]({{}}) in the log contains an [Event]({{< relref "/docs/references/api/grpc#proto.Event" >}}) in the `LogEntry.Event` field and a string description of the event in `LogEntry.entry` field. @@ -169,7 +169,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/api/grpc#skaffoldservice">}}) | protobuf 3 over HTTP | **Examples** @@ -214,7 +214,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 retrieve the state from the server using `gRPC`, first create [`gRPC` client]({{< relref "#creating-a-grpc-client" >}}) as before: ```code func main() { // Create a gRPC client connection to localhost:50051. @@ -230,4 +230,67 @@ func main() { ### Control API -TODO: https://github.com/GoogleContainerTools/skaffold/issues/3143 +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/api/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..afa0993bd81 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/api/grpc" >}}) | +| [HTTP API]({{< relref "/docs/references/api/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/api/_index.md b/docs/content/en/docs/references/api/_index.md index 6c00678b902..e3b4a9fdd6a 100644 --- a/docs/content/en/docs/references/api/_index.md +++ b/docs/content/en/docs/references/api/_index.md @@ -1,457 +1,13 @@ -# Protocol Documentation - +--- +title: "API" +linkTitle: "API" +weight: 30 +--- -## Table of Contents +Skaffold exposes an API for retrieving information about the state of the process and to provide fine grained control over the execution. +For a detailed description of the [Skaffold API]({{}}). -- [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) - - - - -

Top

- -## skaffold.proto - - - - - -### 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. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| artifact | [string](#string) | | artifact name | -| status | [string](#string) | | artifact build status oneof: InProgress, Completed, Failed | -| err | [string](#string) | | error when build status is Failed. | - - - - - - - - -### BuildState -BuildState contains a map of all skaffold artifacts to their current build -states - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| artifacts | [BuildState.ArtifactsEntry](#proto.BuildState.ArtifactsEntry) | repeated | | - - - - - - - - -### BuildState.ArtifactsEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | - - - - - - - - -### DeployEvent -DeployEvent gives the status of a deployment, and will be emitted by Skaffold -anytime a deployment starts or completes, successfully or not. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| status | [string](#string) | | deployment status oneof: InProgress, Completed, Failed | -| err | [string](#string) | | error when status is Failed | - - - - - - - - -### DeployState -DeployState contains the status of the current deploy - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| status | [string](#string) | | | - - - - - - - - -### 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". | -| 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. | -| resourceStatusCheckEvent | [ResourceStatusCheckEvent](#proto.ResourceStatusCheckEvent) | | indicates progress for each kubernetes deployment. | -| fileSyncEvent | [FileSyncEvent](#proto.FileSyncEvent) | | describes the sync status. | - - - - - - - - -### FileSyncEvent -FileSyncEvent describes the sync status. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| fileCount | [int32](#int32) | | number of files synced | -| image | [string](#string) | | the container image to which files are sycned. | -| status | [string](#string) | | status of file sync. one of: Not Started, In progress, Succeeded, Failed. | -| err | [string](#string) | | error in case of status failed. | - - - - - - - - -### FileSyncState -FileSyncState contains the status of the current file sync - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| status | [string](#string) | | | - - - - - - - - -### Intent - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| build | [bool](#bool) | | | -| sync | [bool](#bool) | | | -| deploy | [bool](#bool) | | | - - - - - - - - -### LogEntry -LogEntry describes an event and a string description of the event. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| timestamp | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | timestamp of the event. | -| event | [Event](#proto.Event) | | Event | -| entry | [string](#string) | | description of the event. | - - - - - - - - -### MetaEvent -MetaEvent gives general information regarding Skaffold like version info - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| entry | [string](#string) | | | - - - - - - - - -### PortEvent -PortEvent Event describes each port forwarding event. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| localPort | [int32](#int32) | | local port for forwarded resource | -| remotePort | [int32](#int32) | | remote port is the resource port that will be forwarded. | -| podName | [string](#string) | | pod name if port forwarded resourceType is Pod | -| 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". | -| resourceName | [string](#string) | | name of the resource to forward. | - - - - - - - - -### Request - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | | - - - - - - - - -### ResourceStatusCheckEvent - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| resource | [string](#string) | | | -| status | [string](#string) | | | -| message | [string](#string) | | | -| err | [string](#string) | | | - - - - - - - - -### Response - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| msg | [string](#string) | | | - - - - - - - - -### State -State represents the current state of the Skaffold components - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| buildState | [BuildState](#proto.BuildState) | | | -| deployState | [DeployState](#proto.DeployState) | | | -| forwardedPorts | [State.ForwardedPortsEntry](#proto.State.ForwardedPortsEntry) | repeated | | -| statusCheckState | [StatusCheckState](#proto.StatusCheckState) | | | -| fileSyncState | [FileSyncState](#proto.FileSyncState) | | | - - - - - - - - -### State.ForwardedPortsEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [int32](#int32) | | | -| value | [PortEvent](#proto.PortEvent) | | | - - - - - - - - -### StateResponse - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| state | [State](#proto.State) | | | - - - - - - - - -### StatusCheckEvent -StatusCheck Event describes if the Status check has started, is in progress, has succeeded or failed. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| status | [string](#string) | | | -| message | [string](#string) | | | -| err | [string](#string) | | | - - - - - - - - -### StatusCheckState -StatusCheckState contains the state of status check of current deployed resources. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| status | [string](#string) | | | -| resources | [StatusCheckState.ResourcesEntry](#proto.StatusCheckState.ResourcesEntry) | repeated | | - - - - - - - - -### StatusCheckState.ResourcesEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | - - - - - - - - -### UserIntentRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| intent | [Intent](#proto.Intent) | | | - - - - - - - - - - - - - - -### 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 | +The same API is exposed two ways, through gRPC and HTTP, for which the generated reference can be found below: +* [gRPC API]({{< relref "/docs/references/api/grpc" >}}) +* [HTTP API]({{< relref "/docs/references/api/swagger" >}}) diff --git a/docs/content/en/docs/references/api/grpc.md b/docs/content/en/docs/references/api/grpc.md new file mode 100644 index 00000000000..93b2e8b8db0 --- /dev/null +++ b/docs/content/en/docs/references/api/grpc.md @@ -0,0 +1,430 @@ +--- +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]({{}}). + + + + + +## skaffold.proto + +You can find the source for skaffold.proto [on Github](https://github.com/GoogleContainerTools/skaffold/blob/master/proto/skaffold.proto). + + + +### Services + + + +#### 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) | Returns the state of the current Skaffold execution | +| EventLog | [LogEntry](#proto.LogEntry) stream | [LogEntry](#proto.LogEntry) stream | DEPRECATED. Events should be used instead. TODO remove (https://github.com/GoogleContainerTools/skaffold/issues/3168) | +| Events | [.google.protobuf.Empty](#google.protobuf.Empty) | [LogEntry](#proto.LogEntry) stream | Returns all the events of the current Skaffold execution from the start | +| Execute | [UserIntentRequest](#proto.UserIntentRequest) | [.google.protobuf.Empty](#google.protobuf.Empty) | Allows for a single execution of some or all of the phases (build, sync, deploy) in case autoBuild, autoDeploy or autoSync are disabled. | +| Handle | [Event](#proto.Event) | [.google.protobuf.Empty](#google.protobuf.Empty) | EXPERIMENTAL. It allows for custom events to be implemented in custom builders for example. | + + + + +### 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. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| artifact | [string](#string) | | artifact name | +| status | [string](#string) | | artifact build status oneof: InProgress, Completed, Failed | +| err | [string](#string) | | error when build status is Failed. | + + + + + + + + +#### BuildState +`BuildState` maps Skaffold artifacts to their current build states + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| artifacts | [BuildState.ArtifactsEntry](#proto.BuildState.ArtifactsEntry) | repeated | A map of `artifact name -> build-state`. Artifact name is defined in the `skaffold.yaml`. The `build-state` can be:
- `"Not started"`: not yet started
- `"In progress"`: build started
- `"Complete"`: build succeeded
- `"Failed"`: build failed | + + + + + + + + +#### BuildState.ArtifactsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +#### DeployEvent +`DeployEvent` represents the status of a deployment, and is emitted by Skaffold +anytime a deployment starts or completes, successfully or not. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| status | [string](#string) | | deployment status oneof: InProgress, Completed, Failed | +| err | [string](#string) | | error when status is Failed | + + + + + + + + +#### DeployState +`DeployState` describes the status of the current deploy + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| status | [string](#string) | | | + + + + + + + + +#### Event +`Event` describes an event in the Skaffold process. +It is one of MetaEvent, BuildEvent, DeployEvent, PortEvent, StatusCheckEvent, ResourceStatusCheckEvent or FileSyncEvent. + + +| 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". | +| 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. | +| resourceStatusCheckEvent | [ResourceStatusCheckEvent](#proto.ResourceStatusCheckEvent) | | indicates progress for each kubernetes deployment. | +| fileSyncEvent | [FileSyncEvent](#proto.FileSyncEvent) | | describes the sync status. | + + + + + + + + +#### FileSyncEvent +FileSyncEvent describes the sync status. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| fileCount | [int32](#int32) | | number of files synced | +| image | [string](#string) | | the container image to which files are sycned. | +| status | [string](#string) | | status of file sync. one of: Not Started, In progress, Succeeded, Failed. | +| err | [string](#string) | | error in case of status failed. | + + + + + + + + +#### FileSyncState +`FileSyncState` contains the status of the current file sync + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| status | [string](#string) | | | + + + + + + + + +#### Intent +Intent represents user intents for a given phase to be unblocked, once. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| 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 describes an event and a string description of the event. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| timestamp | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | timestamp of the event. | +| event | [Event](#proto.Event) | | the actual event that is one of | +| entry | [string](#string) | | description of the event. | + + + + + + + + +#### MetaEvent +`MetaEvent` provides general information regarding Skaffold + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| entry | [string](#string) | | entry, for example: `"Starting Skaffold: {Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"` | + + + + + + + + +#### PortEvent +PortEvent Event describes each port forwarding event. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| localPort | [int32](#int32) | | local port for forwarded resource | +| remotePort | [int32](#int32) | | remote port is the resource port that will be forwarded. | +| podName | [string](#string) | | pod name if port forwarded resourceType is Pod | +| 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". | +| resourceName | [string](#string) | | name of the resource to forward. | + + + + + + + + +#### Request + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | | + + + + + + + + +#### ResourceStatusCheckEvent +A Resource StatusCheck Event, indicates progress for each kubernetes deployment. +For every resource, there will be exactly one event with `status` *Succeeded* or *Failed* event. +There can be multiple events with `status` *Pending*. +Skaffold polls for resource status every 0.5 second. If the resource status changes, an event with `status` “Pending”, “Complete” and “Failed” +will be sent with the new status. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| resource | [string](#string) | | | +| status | [string](#string) | | | +| message | [string](#string) | | | +| err | [string](#string) | | | + + + + + + + + +#### Response + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| msg | [string](#string) | | | + + + + + + + + +#### State +`State` represents the current state of the Skaffold components + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| buildState | [BuildState](#proto.BuildState) | | | +| deployState | [DeployState](#proto.DeployState) | | | +| forwardedPorts | [State.ForwardedPortsEntry](#proto.State.ForwardedPortsEntry) | repeated | | +| statusCheckState | [StatusCheckState](#proto.StatusCheckState) | | | +| fileSyncState | [FileSyncState](#proto.FileSyncState) | | | + + + + + + + + +#### State.ForwardedPortsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [int32](#int32) | | | +| value | [PortEvent](#proto.PortEvent) | | | + + + + + + + + +#### StateResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| state | [State](#proto.State) | | | + + + + + + + + +#### StatusCheckEvent +`StatusCheckEvent` describes if the status check for kubernetes rollout has started, is in progress, has succeeded or failed. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| status | [string](#string) | | | +| message | [string](#string) | | | +| err | [string](#string) | | | + + + + + + + + +#### StatusCheckState +`StatusCheckState` describes the state of status check of current deployed resources. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| status | [string](#string) | | | +| resources | [StatusCheckState.ResourcesEntry](#proto.StatusCheckState.ResourcesEntry) | repeated | A map of `resource name -> status-check-state`. Where `resource-name` is the kubernetes resource name. The `status-check-state` can be
- `"Not started"`: indicates that `status-check` has just started.
- `"In progress"`: InProgress is sent after every resource check is complete.
- `"Succeeded"`: - `"Failed"`: | + + + + + + + + +#### StatusCheckState.ResourcesEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +#### UserIntentRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| intent | [Intent](#proto.Intent) | | | + + + + + + + + + + + + + diff --git a/docs/content/en/docs/references/api/swagger.md b/docs/content/en/docs/references/api/swagger.md new file mode 100644 index 00000000000..53aed8606aa --- /dev/null +++ b/docs/content/en/docs/references/api/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/cli/_index.md b/docs/content/en/docs/references/cli/_index.md index 159d789ae4f..610f896faa6 100644 --- a/docs/content/en/docs/references/cli/_index.md +++ b/docs/content/en/docs/references/cli/_index.md @@ -1,7 +1,7 @@ --- title: "CLI" linkTitle: "CLI" -weight: 110 +weight: 1 --- Skaffold command-line interface provides the following commands: diff --git a/docs/content/en/docs/references/cli/index_header b/docs/content/en/docs/references/cli/index_header index d779b89a633..1c8396bb688 100644 --- a/docs/content/en/docs/references/cli/index_header +++ b/docs/content/en/docs/references/cli/index_header @@ -1,7 +1,7 @@ --- title: "CLI" linkTitle: "CLI" -weight: 110 +weight: 1 --- Skaffold command-line interface provides the following commands: 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 209824a0e0d..a8b4a271f5e 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 --- This document sets out the deprecation policy for Skaffold, and outlines how the Skaffold project will approach the introduction of breaking changes over time. 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/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 }} -