From 41a59a81d4f4878875b182b609e28b1042c28115 Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 16 Oct 2019 01:38:08 -0700 Subject: [PATCH 1/9] draft pages --- .../en/docs/concepts/api_server/_index.md | 50 +++++++++++++++++++ .../content/en/docs/concepts/events/_index.md | 23 +++++++++ 2 files changed, 73 insertions(+) create mode 100644 docs/content/en/docs/concepts/api_server/_index.md create mode 100644 docs/content/en/docs/concepts/events/_index.md diff --git a/docs/content/en/docs/concepts/api_server/_index.md b/docs/content/en/docs/concepts/api_server/_index.md new file mode 100644 index 00000000000..8333f87983d --- /dev/null +++ b/docs/content/en/docs/concepts/api_server/_index.md @@ -0,0 +1,50 @@ +--- +title: "Skaffold API Server" +linkTitle: "Skaffold API Server" +weight: 40 +--- + + +This page discusses the Skaffold API Server. + +Skaffold exposes a API server over its lifetime. The API server is the primary way +to get notifications regarding the different phases in a pipeline run. + + +## Skaffold API Server +Skaffold creates `gRPC HTTP` and `gRPC` server. + + +## gRPC Server + +gRPC API server is exposed on port `50051` by default. If the port is busy, Skaffold will find the next available port. +You can grab the port from Skaffold logs. + +```code +$ skaffold dev +WARN[0000] port 50051 for gRPC server already in use: using 50053 instead +``` +You can also specify a port on the command line with flag `--rpc-port`. + + +## gRPC REST Server +REST API server is exposed on port `50052` by default. If the port is busy, Skaffold will find the next available port. +You can grab the port from Skaffold logs. + +```code +$ skaffold dev +WARN[0000] port 50052 for gRPC HTTP server already in use: using 50055 instead +``` +You can also specify a port on the command line with flag `--rpc-http-port`. + + +## Skaffold APIS Endpoints +Skaffold API Server exposes following endpoints. + +### Events API + + +### State API + + +### Control API diff --git a/docs/content/en/docs/concepts/events/_index.md b/docs/content/en/docs/concepts/events/_index.md new file mode 100644 index 00000000000..42d658983c4 --- /dev/null +++ b/docs/content/en/docs/concepts/events/_index.md @@ -0,0 +1,23 @@ +--- +title: "Skaffold Events" +linkTitle: "Skaffold Events" +weight: 40 +--- + +This page discusses the Skaffold Events. + +Skaffold provides a continous development mode [`skaffold dev`](../modes/) which builds, deploys +your application on changes. In a single development loop, one or more container images +may be built and deployed. The time taken for the changes to deploy varies. + +Skaffold exposes events for users to get notified when phases within a development loop +complete. +You can use these events to automate next steps in your development workflow. + +e.g: when making a change to port-forwarded frontend service, reload the +browser url after the service is deployed and running to test changes. + +## Using the Events API +To get Skaffold events curl the [events API endpoint](#events) on port `50052` + +s From b732fb03fe0981fd16a90c9853ced43bd0b3cc3c Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 16 Oct 2019 11:33:20 -0700 Subject: [PATCH 2/9] one file only --- docs/content/en/docs/concepts/api/_index.md | 73 +++++++++++++++++++ .../en/docs/concepts/api_server/_index.md | 50 ------------- .../content/en/docs/concepts/events/_index.md | 23 ------ 3 files changed, 73 insertions(+), 73 deletions(-) create mode 100644 docs/content/en/docs/concepts/api/_index.md delete mode 100644 docs/content/en/docs/concepts/api_server/_index.md delete mode 100644 docs/content/en/docs/concepts/events/_index.md diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md new file mode 100644 index 00000000000..97cac5b5654 --- /dev/null +++ b/docs/content/en/docs/concepts/api/_index.md @@ -0,0 +1,73 @@ +--- +title: "Skaffold API" +linkTitle: "Skaffold API" +weight: 40 +--- + + +This page discusses the Skaffold API. + +Skaffold exposes a API server over its lifetime. The API server is the primary way +to get notifications regarding the different phases in a pipeline run. The API server +also provides fine grain controls to Skaffold's individual components: build, deploy and sync, +as opposed to relying on Skaffold’s built-in trigger mechanisms. + + +## Skaffold API +Skaffold API is restful and `gRPC` based, so it works with any language that has an HTTP library, such as cURL and urllib. +The API server runs on localhost at predefined ports. +The protos used can be found here. (todo add link) + +## gRPC Server + +gRPC API server is exposed on port `50051` by default. If the port is busy, Skaffold will find the next available port. +You can grab the port from Skaffold logs. + +```code +$ skaffold dev +WARN[0000] port 50051 for gRPC server already in use: using 50053 instead +``` +You can also specify a port on the command line with flag `--rpc-port`. + + +## gRPC REST Server +REST API server is exposed on port `50052` by default. If the port is busy, Skaffold will find the next available port. +You can grab the port from Skaffold logs. + +```code +$ skaffold dev +WARN[0000] port 50052 for gRPC HTTP server already in use: using 50055 instead +``` +You can also specify a port on the command line with flag `--rpc-http-port`. + + +## Skaffold API +Skaffold API Server exposes following endpoints. + +### GET /v1/events + +Skaffold provides a continuous development mode [`skaffold dev`](../modes/#skaffold_dev) which builds, deploys +your application on changes. In a single development loop, one or more container images +may be built and deployed. The time taken for the changes to deploy varies. + +Skaffold exposes events for users to get notified when phases within a development loop +complete. +You can use these events to automate next steps in your development workflow. + +e.g: when making a change to port-forwarded frontend service, reload the +browser url after the service is deployed and running to test changes. + +Here is way to get events for a `skaffold dev` [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) +```code + curl localhost:50052/v1/events +{"result":{"timestamp":"2019-10-16T18:26:11.385251549Z","event":{"metaEvent":{"entry":"Starting Skaffold: \u0026{Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate:2019-10-03T15:01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"}}}} +{"result":{"timestamp":"2019-10-16T18:26:11.436231589Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"In Progress"}},"entry":"Build started for artifact gcr.io/k8s-skaffold/skaffold-example"}} +{"result":{"timestamp":"2019-10-16T18:26:12.010124246Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"Complete"}},"entry":"Build completed for artifact gcr.io/k8s-skaffold/skaffold-example"}} +{"result":{"timestamp":"2019-10-16T18:26:12.391721823Z","event":{"deployEvent":{"status":"In Progress"}},"entry":"Deploy started"}} +{"result":{"timestamp":"2019-10-16T18:26:12.847239740Z","event":{"deployEvent":{"status":"Complete"}},"entry":"Deploy complete"}} +.. +``` +### Get /v1/state + + +### Get /v1/execute diff --git a/docs/content/en/docs/concepts/api_server/_index.md b/docs/content/en/docs/concepts/api_server/_index.md deleted file mode 100644 index 8333f87983d..00000000000 --- a/docs/content/en/docs/concepts/api_server/_index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Skaffold API Server" -linkTitle: "Skaffold API Server" -weight: 40 ---- - - -This page discusses the Skaffold API Server. - -Skaffold exposes a API server over its lifetime. The API server is the primary way -to get notifications regarding the different phases in a pipeline run. - - -## Skaffold API Server -Skaffold creates `gRPC HTTP` and `gRPC` server. - - -## gRPC Server - -gRPC API server is exposed on port `50051` by default. If the port is busy, Skaffold will find the next available port. -You can grab the port from Skaffold logs. - -```code -$ skaffold dev -WARN[0000] port 50051 for gRPC server already in use: using 50053 instead -``` -You can also specify a port on the command line with flag `--rpc-port`. - - -## gRPC REST Server -REST API server is exposed on port `50052` by default. If the port is busy, Skaffold will find the next available port. -You can grab the port from Skaffold logs. - -```code -$ skaffold dev -WARN[0000] port 50052 for gRPC HTTP server already in use: using 50055 instead -``` -You can also specify a port on the command line with flag `--rpc-http-port`. - - -## Skaffold APIS Endpoints -Skaffold API Server exposes following endpoints. - -### Events API - - -### State API - - -### Control API diff --git a/docs/content/en/docs/concepts/events/_index.md b/docs/content/en/docs/concepts/events/_index.md deleted file mode 100644 index 42d658983c4..00000000000 --- a/docs/content/en/docs/concepts/events/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Skaffold Events" -linkTitle: "Skaffold Events" -weight: 40 ---- - -This page discusses the Skaffold Events. - -Skaffold provides a continous development mode [`skaffold dev`](../modes/) which builds, deploys -your application on changes. In a single development loop, one or more container images -may be built and deployed. The time taken for the changes to deploy varies. - -Skaffold exposes events for users to get notified when phases within a development loop -complete. -You can use these events to automate next steps in your development workflow. - -e.g: when making a change to port-forwarded frontend service, reload the -browser url after the service is deployed and running to test changes. - -## Using the Events API -To get Skaffold events curl the [events API endpoint](#events) on port `50052` - -s From d77075163767de0e861785739c89fe6d4319ef9d Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 16 Oct 2019 11:38:12 -0700 Subject: [PATCH 3/9] some minor changes --- docs/content/en/docs/concepts/api/_index.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md index 97cac5b5654..a8dcb318873 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/concepts/api/_index.md @@ -4,13 +4,11 @@ linkTitle: "Skaffold API" weight: 40 --- - -This page discusses the Skaffold API. - -Skaffold exposes a API server over its lifetime. The API server is the primary way -to get notifications regarding the different phases in a pipeline run. The API server -also provides fine grain controls to Skaffold's individual components: build, deploy and sync, -as opposed to relying on Skaffold’s built-in trigger mechanisms. +When using `skaffold dev` or `skaffold debug`, Skaffold exposes a API server over its lifetime. +The API server is the primary way tools like IDEs to integrate with skaffold and subscribe to events +regarding the different phases in a pipeline run and to get the overall state of the pipeline. +The API server also provides fine grain controls to Skaffold's individual components: +build, deploy and sync, as opposed to relying on Skaffold’s built-in trigger mechanisms. ## Skaffold API From 35660800266cad1155e0006390b0796e7e290d5e Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 16 Oct 2019 11:41:31 -0700 Subject: [PATCH 4/9] fix link --- docs/content/en/docs/concepts/api/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md index a8dcb318873..f5683f185ea 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/concepts/api/_index.md @@ -16,7 +16,7 @@ Skaffold API is restful and `gRPC` based, so it works with any language that has The API server runs on localhost at predefined ports. The protos used can be found here. (todo add link) -## gRPC Server +### gRPC Server gRPC API server is exposed on port `50051` by default. If the port is busy, Skaffold will find the next available port. You can grab the port from Skaffold logs. @@ -28,7 +28,7 @@ WARN[0000] port 50051 for gRPC server already in use: using 50053 instead You can also specify a port on the command line with flag `--rpc-port`. -## gRPC REST Server +### gRPC REST Server REST API server is exposed on port `50052` by default. If the port is busy, Skaffold will find the next available port. You can grab the port from Skaffold logs. From a771a9c7e29f8a45319cd37cf9e1de60a9fa0336 Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 16 Oct 2019 15:11:51 -0700 Subject: [PATCH 5/9] Apply suggestions from code review nick's suggestion. Co-Authored-By: Nick Kubala --- docs/content/en/docs/concepts/api/_index.md | 32 ++++++++++----------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md index f5683f185ea..6ca13b6e95a 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/concepts/api/_index.md @@ -4,43 +4,43 @@ linkTitle: "Skaffold API" weight: 40 --- -When using `skaffold dev` or `skaffold debug`, Skaffold exposes a API server over its lifetime. -The API server is the primary way tools like IDEs to integrate with skaffold and subscribe to events -regarding the different phases in a pipeline run and to get the overall state of the pipeline. -The API server also provides fine grain controls to Skaffold's individual components: -build, deploy and sync, as opposed to relying on Skaffold’s built-in trigger mechanisms. +When running `skaffold dev` or `skaffold debug`, Skaffold starts a server that exposes an API over the lifetime of the run. +This API is the primary way tools like IDEs integrate with skaffold, both to subscribe to an event log +created from the different phases in a pipeline run, and to get a snapshot of the overall state of the pipeline at any given time during the run. +The API also provides fine grain controls over the individual components of the Skaffold +pipeline (build, deploy and sync), as opposed to relying on Skaffold’s built-in trigger mechanisms. ## Skaffold API -Skaffold API is restful and `gRPC` based, so it works with any language that has an HTTP library, such as cURL and urllib. -The API server runs on localhost at predefined ports. -The protos used can be found here. (todo add link) +The Skaffold API is both restful and `gRPC` based, so it can be accessed directly through a terminal via `curl`, or through your favorite client library for issuing HTTP requests or writing `gRPC` clients. +The server is hosted locally on the Skaffold host machine, and will serve by default on ports 50051 and 50052, though these ports can be configured through the `--rpc-port` and `--rpc-http-port` flags. +The server's protocol is based on protobufs: documentation for these can be found here. TODO (tejaldesai): add link ### gRPC Server -gRPC API server is exposed on port `50051` by default. If the port is busy, Skaffold will find the next available port. -You can grab the port from Skaffold logs. +The gRPC API is exposed on port `50051` by default. If this port is busy, Skaffold will find the next available port. +You can find this port from Skaffold's logs on startup. ```code $ skaffold dev WARN[0000] port 50051 for gRPC server already in use: using 50053 instead ``` -You can also specify a port on the command line with flag `--rpc-port`. +You can also specify a port on the command line with the `--rpc-port` flag. -### gRPC REST Server -REST API server is exposed on port `50052` by default. If the port is busy, Skaffold will find the next available port. +### HTTP (REST) API +The HTTP API is exposed on port `50052` by default. As with the gRPC API, if this port is busy, Skaffold will find the next available port, and the final port can be found from Skaffold's startup logs. You can grab the port from Skaffold logs. ```code $ skaffold dev WARN[0000] port 50052 for gRPC HTTP server already in use: using 50055 instead ``` -You can also specify a port on the command line with flag `--rpc-http-port`. +You can also specify a port on the command line with the `--rpc-http-port` flag. ## Skaffold API -Skaffold API Server exposes following endpoints. +Skaffold's API exposes the following endpoints: ### GET /v1/events @@ -52,7 +52,7 @@ Skaffold exposes events for users to get notified when phases within a developme complete. You can use these events to automate next steps in your development workflow. -e.g: when making a change to port-forwarded frontend service, reload the +For example, when making a change to port-forwarded frontend service, reload the browser url after the service is deployed and running to test changes. Here is way to get events for a `skaffold dev` [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) From b1a7fe5ff10859f906920792b84a4610883206bd Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 16 Oct 2019 18:31:04 -0700 Subject: [PATCH 6/9] Update docs/content/en/docs/concepts/api/_index.md Co-Authored-By: Balint Pato --- docs/content/en/docs/concepts/api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md index 6ca13b6e95a..cb315273068 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/concepts/api/_index.md @@ -55,7 +55,7 @@ You can use these events to automate next steps in your development workflow. For example, when making a change to port-forwarded frontend service, reload the browser url after the service is deployed and running to test changes. -Here is way to get events for a `skaffold dev` [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) +An example output using curl to get events for a `skaffold dev` execution on our [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) ```code curl localhost:50052/v1/events {"result":{"timestamp":"2019-10-16T18:26:11.385251549Z","event":{"metaEvent":{"entry":"Starting Skaffold: \u0026{Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate:2019-10-03T15:01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"}}}} From 906db352f9084e1d4a2a6a14916d46593eee73e5 Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Thu, 17 Oct 2019 16:20:55 -0700 Subject: [PATCH 7/9] Apply suggestions from code review Co-Authored-By: Balint Pato --- docs/content/en/docs/concepts/api/_index.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md index cb315273068..40e30d76571 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/concepts/api/_index.md @@ -5,16 +5,19 @@ weight: 40 --- When running `skaffold dev` or `skaffold debug`, Skaffold starts a server that exposes an API over the lifetime of the run. -This API is the primary way tools like IDEs integrate with skaffold, both to subscribe to an event log -created from the different phases in a pipeline run, and to get a snapshot of the overall state of the pipeline at any given time during the run. -The API also provides fine grain controls over the individual components of the Skaffold -pipeline (build, deploy and sync), as opposed to relying on Skaffold’s built-in trigger mechanisms. +Besides the CLI, this API is the primary way tools like IDEs integrate with Skaffold for **retrieving information about the pipeline** and for **controlling the phases in the pipeline**. To retrieve information of the Skaffold pipeline, the Skaffold API provides two main functionalities: +- a streaming event log +created from the different phases in a pipeline run +- and a snapshot of the overall state of the pipeline at any given time during the run. +The API also provides fine grained control over the individual phases of the Skaffold +pipeline (build, deploy and sync), as opposed to relying on Skaffold’s automation. ## Skaffold API -The Skaffold API is both restful and `gRPC` based, so it can be accessed directly through a terminal via `curl`, or through your favorite client library for issuing HTTP requests or writing `gRPC` clients. -The server is hosted locally on the Skaffold host machine, and will serve by default on ports 50051 and 50052, though these ports can be configured through the `--rpc-port` and `--rpc-http-port` flags. -The server's protocol is based on protobufs: documentation for these can be found here. TODO (tejaldesai): add link +The Skaffold API is `gRPC` based, and it is also exposed via the gRPC gateway as a JSON over HTTP service. +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](/#). +{{% todo 1703 %}} ### gRPC Server From 10f456c4c6786aced7154b293305818117550267 Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Wed, 30 Oct 2019 12:41:21 -0700 Subject: [PATCH 8/9] Better event api docs. Added proto description and code snippets --- docs/content/en/docs/concepts/api/_index.md | 229 +++++++++++++++--- docs/content/en/docs/references/_index.md | 3 +- docs/content/en/docs/references/api/_index.md | 71 +++--- docs/static/stylesheets/tabs.css | 1 - proto/skaffold.pb.go | 10 + proto/skaffold.proto | 68 ++++-- 6 files changed, 282 insertions(+), 100 deletions(-) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/concepts/api/_index.md index 40e30d76571..1530aa52260 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/concepts/api/_index.md @@ -3,63 +3,112 @@ title: "Skaffold API" linkTitle: "Skaffold API" weight: 40 --- +When running [`skaffold dev`]({{< relref "/docs/workflows/dev" >}}) or [`skaffold debug`]({{< relref "/docs/workflows/debug" >}}), +Skaffold starts a server that exposes an API over the lifetime of the Skaffold process. +Besides the CLI, this API is the primary way tools like IDEs integrate with Skaffold for **retrieving information about the +pipeline** and for **controlling the phases in the pipeline**. -When running `skaffold dev` or `skaffold debug`, Skaffold starts a server that exposes an API over the lifetime of the run. -Besides the CLI, this API is the primary way tools like IDEs integrate with Skaffold for **retrieving information about the pipeline** and for **controlling the phases in the pipeline**. To retrieve information of the Skaffold pipeline, the Skaffold API provides two main functionalities: -- a streaming event log -created from the different phases in a pipeline run -- and a snapshot of the overall state of the pipeline at any given time during the run. -The API also provides fine grained control over the individual phases of the Skaffold -pipeline (build, deploy and sync), as opposed to relying on Skaffold’s automation. +To retrieve information of the Skaffold pipeline, the Skaffold API provides two main functionalities: + + * A [streaming event log]({{< relref "/docs/concepts/api#events-api">}}) created from the different phases in a pipeline run and + + * A snapshot of the [overall state]({{< relref "/docs/concepts/api#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/concepts/api#controlling-build-sync-deploy" >}}) +the individual phases of the pipeline (build, deploy and sync). -## Skaffold API + +## Connecting to the Skaffold API The Skaffold API is `gRPC` based, and it is also exposed via the gRPC gateway as a JSON over HTTP service. -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](/#). -{{% todo 1703 %}} +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. -### gRPC Server +The server's gRPC service definitions and message protos can be found [here]({{< relref "/docs/references/api" >}}). -The gRPC API is exposed on port `50051` by default. If this port is busy, Skaffold will find the next available port. -You can find this port from Skaffold's logs on startup. + +### HTTP server +The HTTP API is exposed on port `50052` by default. The default HTTP port can be overriden with the `--rpc-http-port` flag. +If the HTTP API port is taken, Skaffold will find the next available port. +The final port can be found from Skaffold's startup logs. ```code $ skaffold dev -WARN[0000] port 50051 for gRPC server already in use: using 50053 instead -``` -You can also specify a port on the command line with the `--rpc-port` flag. +WARN[0000] port 50052 for gRPC HTTP server already in use: using 50055 instead +``` +### gRPC Server -### HTTP (REST) API -The HTTP API is exposed on port `50052` by default. As with the gRPC API, if this port is busy, Skaffold will find the next available port, and the final port can be found from Skaffold's startup logs. -You can grab the port from Skaffold logs. +The gRPC API is exposed on port `50051` by default and can be overriden with the `--rpc-port` flag. +As with the HTTP API, if this port is taken, Skaffold will find the next available port. +You can find this port from Skaffold's logs on startup. ```code $ skaffold dev -WARN[0000] port 50052 for gRPC HTTP server already in use: using 50055 instead -``` -You can also specify a port on the command line with the `--rpc-http-port` flag. +WARN[0000] port 50051 for gRPC server already in use: using 50053 instead +``` + +#### Creating a gRPC Client +To connect to the `gRPC` server at default port `50051` use the following code snippet. + +{{< alert title="Note" >}} +The skaffold gRPC server is not an HTTPS service, hence we need to specify .WithInSecure() +{{}} + +```golang +import ( + "log" + pb "github.com/GoogleContainerTools/skaffold/proto" + "google.golang.org/grpc" +) + +func main(){ + conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure()) + if err != nil { + log.Fatalf("fail to dial: %v", err) + } + defer conn.Close() + client := pb.NewSkaffoldServiceClient(conn) +} +``` + +## API structure -## Skaffold API -Skaffold's API exposes the following endpoints: +Skaffold's API exposes the three main endpoints: -### GET /v1/events +* Events API - stream of lifecycle events +* State API - retrieve the current state +* Control API - control build/deploy/sync -Skaffold provides a continuous development mode [`skaffold dev`](../modes/#skaffold_dev) which builds, deploys +### Events API + +Skaffold provides a continuous development mode [`skaffold dev`]({{< relref "/docs/workflows/dev" >}}) which builds, deploys your application on changes. In a single development loop, one or more container images -may be built and deployed. The time taken for the changes to deploy varies. +may be built and deployed. -Skaffold exposes events for users to get notified when phases within a development loop -complete. -You can use these events to automate next steps in your development workflow. +Skaffold exposes events for clients to get notified when phases within a development loop +start, succeed or fail. +Tools that integrate with Skaffold can use these events to kick-off parts of the development workflow depending on them. -For example, when making a change to port-forwarded frontend service, reload the -browser url after the service is deployed and running to test changes. +Example scenarios: -An example output using curl to get events for a `skaffold dev` execution on our [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) -```code +* port forwarding events are used by Cloud Code to attach debuggers automatically to running containers. +* when a port-forwarded frontend service is redeployed successfully, kick-off a suite of Selenium tests can be executed to test changes. + +**Event API contract** + +| 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 | + + +**Examples** + +{{% tabs %}} +{{% tab "HTTP API" %}} +Using `curl` and `HTTP_RPC_PORT=50052`, an example output of a `skaffold dev` execution on our [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) +```bash curl localhost:50052/v1/events {"result":{"timestamp":"2019-10-16T18:26:11.385251549Z","event":{"metaEvent":{"entry":"Starting Skaffold: \u0026{Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate:2019-10-03T15:01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"}}}} {"result":{"timestamp":"2019-10-16T18:26:11.436231589Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"In Progress"}},"entry":"Build started for artifact gcr.io/k8s-skaffold/skaffold-example"}} @@ -68,7 +117,113 @@ An example output using curl to get events for a `skaffold dev` execution on our {"result":{"timestamp":"2019-10-16T18:26:12.847239740Z","event":{"deployEvent":{"status":"Complete"}},"entry":"Deploy complete"}} .. ``` -### Get /v1/state +{{% /tab %}} +{{% tab "gRPC API" %}} +To get events from the `gRPC` server, first create [`gRPC` client]({{< relref "/docs/concepts/api#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 + logStream, err := client.Events(ctx) + if err != nil { + log.Fatalf("could not get events: %v", err) + } + for { + entry, err := logStream.Recv() + if err == io.EOF { + break + } + if err != nil { + log.Fatal(err) + } + log.Println(entry) + } +} +``` +{{% /tab %}} +{{% /tabs %}} + +Each [Entry log]({{}}) contains an [Event]({{< relref "/docs/references/api#proto.Event" >}}) in the `LogEntry.Event` field and +a string description of the event in `LogEntry.entry` field. + + +### State API + +The State API provides a snapshot of the current state of the following components: + +- build state per artifacts +- deploy state +- file sync state +- status check state per resource +- port-forwarded resources + +**Event API contract** + +| 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 | + + +**Examples** +{{% tabs %}} +{{% tab "HTTP API" %}} +Using `curl` and `HTTP_RPC_PORT=50052`, an example output of a `skaffold dev` execution on our [microservices example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/microservices) +```bash + curl localhost:50052/v1/state | jq + { + "buildState": { + "artifacts": { + "gcr.io/k8s-skaffold/leeroy-app": "Complete", + "gcr.io/k8s-skaffold/leeroy-web": "Complete" + } + }, + "deployState": { + "status": "Complete" + }, + "forwardedPorts": { + "9000": { + "localPort": 9000, + "remotePort": 8080, + "namespace": "default", + "resourceType": "deployment", + "resourceName": "leeroy-web" + }, + "50055": { + "localPort": 50055, + "remotePort": 50051, + "namespace": "default", + "resourceType": "service", + "resourceName": "leeroy-app" + } + }, + "statusCheckState": { + "status": "Succeeded" + }, + "fileSyncState": { + "status": "Not Started" + } + } +``` +{{% /tab %}} +{{% tab "gRPC API" %}} +To get events over `gRPC` server, first create [`gRPC` client]({{< relref "/docs/concepts/api#creating-a-grpc-client" >}}) +```code +func main() { + // Create a gRPC client connection to localhost:50051. + // See code above + ctx, ctxCancel := context.WithCancel(context.Background()) + defer ctxCancel() + grpcState, err = client.GetState(ctx, &empty.Empty{}) + ... +} +``` +{{% /tab %}} +{{% /tabs %}} +### Controlling Build/Sync/Deploy -### Get /v1/execute +TODO: https://github.com/GoogleContainerTools/skaffold/issues/3143 \ No newline at end of file diff --git a/docs/content/en/docs/references/_index.md b/docs/content/en/docs/references/_index.md index a45ef415556..fe9c985c550 100755 --- a/docs/content/en/docs/references/_index.md +++ b/docs/content/en/docs/references/_index.md @@ -9,5 +9,6 @@ weight: 100 | [CLI]({{< relref "/docs/references/cli" >}}) | | [skaffold.yaml]({{< relref "/docs/references/yaml" >}}) | | [Deprecation Policy]({{< relref "/docs/references/deprecation" >}}) | -| [Privacy Settings] (/docs/references/privacy) | +| [Privacy Settings] ({{< relref "/docs/references/privacy" >}}) | +| [Skaffold API]({{< relref "/docs/references/api" >}}) | diff --git a/docs/content/en/docs/references/api/_index.md b/docs/content/en/docs/references/api/_index.md index c2338119501..f87682710bb 100644 --- a/docs/content/en/docs/references/api/_index.md +++ b/docs/content/en/docs/references/api/_index.md @@ -46,14 +46,15 @@ ### BuildEvent - +BuildEvent describes if the build status per artifact. Status could be one of +"InProgress", "Completed" or "Failed". | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| artifact | [string](#string) | | | -| status | [string](#string) | | | -| err | [string](#string) | | | +| artifact | [string](#string) | | artifact name | +| status | [string](#string) | | artifact build status oneof: InProgress, Completed, Failed | +| err | [string](#string) | | error when build status is Failed. | @@ -95,13 +96,13 @@ states ### DeployEvent - +Deploy Event describes if the deployment has started, is in progress or is complete. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| status | [string](#string) | | | -| err | [string](#string) | | | +| status | [string](#string) | | deployment status oneof: InProgress, Completed, Failed | +| err | [string](#string) | | error when status is Failed | @@ -126,18 +127,18 @@ DeployState contains the status of the current deploy ### Event - +Event is one of the following events. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| metaEvent | [MetaEvent](#proto.MetaEvent) | | | -| buildEvent | [BuildEvent](#proto.BuildEvent) | | | -| deployEvent | [DeployEvent](#proto.DeployEvent) | | | -| portEvent | [PortEvent](#proto.PortEvent) | | | -| statusCheckEvent | [StatusCheckEvent](#proto.StatusCheckEvent) | | | -| resourceStatusCheckEvent | [ResourceStatusCheckEvent](#proto.ResourceStatusCheckEvent) | | | -| fileSyncEvent | [FileSyncEvent](#proto.FileSyncEvent) | | | +| 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. | @@ -147,15 +148,15 @@ DeployState contains the status of the current deploy ### FileSyncEvent - +FileSyncEvent describes the sync status. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| fileCount | [int32](#int32) | | | -| image | [string](#string) | | | -| status | [string](#string) | | | -| err | [string](#string) | | | +| 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. | @@ -197,14 +198,14 @@ FileSyncState contains the status of the current file sync ### LogEntry - +LogEntry describes an event and a string description of the event. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| timestamp | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | | -| event | [Event](#proto.Event) | | | -| entry | [string](#string) | | | +| timestamp | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | timestamp of the event. | +| event | [Event](#proto.Event) | | Event | +| entry | [string](#string) | | description of the event. | @@ -214,7 +215,7 @@ FileSyncState contains the status of the current file sync ### MetaEvent - +MetaEvent gives general information regarding Skaffold like version info | Field | Type | Label | Description | @@ -229,19 +230,19 @@ FileSyncState contains the status of the current file sync ### PortEvent - +PortEvent Event describes each port forwarding event. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| localPort | [int32](#int32) | | | -| remotePort | [int32](#int32) | | | -| podName | [string](#string) | | | -| containerName | [string](#string) | | | -| namespace | [string](#string) | | | +| 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) | | | -| resourceName | [string](#string) | | | +| resourceType | [string](#string) | | resource type e.g. "pod", "service". | +| resourceName | [string](#string) | | name of the resource to forward. | @@ -299,7 +300,7 @@ FileSyncState contains the status of the current file sync ### State - +State represents the current state of the Skaffold components | Field | Type | Label | Description | @@ -349,7 +350,7 @@ FileSyncState contains the status of the current file sync ### StatusCheckEvent - +StatusCheck Event describes if the Status check has started, is in progress, has succeeded or failed. | Field | Type | Label | Description | diff --git a/docs/static/stylesheets/tabs.css b/docs/static/stylesheets/tabs.css index cad791dae1d..c0d2f5ab6c3 100644 --- a/docs/static/stylesheets/tabs.css +++ b/docs/static/stylesheets/tabs.css @@ -13,7 +13,6 @@ li.nav-tab { float: left; text-align: center; text-decoration: none; - text-transform: uppercase; font-weight: bold; color: darkgray; font-size: 14px; diff --git a/proto/skaffold.pb.go b/proto/skaffold.pb.go index e3f45d51a83..fbdbc08b4a0 100644 --- a/proto/skaffold.pb.go +++ b/proto/skaffold.pb.go @@ -144,6 +144,7 @@ func (m *Request) GetName() string { return "" } +// State represents the current state of the Skaffold components type State struct { BuildState *BuildState `protobuf:"bytes,1,opt,name=buildState,proto3" json:"buildState,omitempty"` DeployState *DeployState `protobuf:"bytes,2,opt,name=deployState,proto3" json:"deployState,omitempty"` @@ -384,6 +385,7 @@ func (m *FileSyncState) GetStatus() string { return "" } +// Event is one of the following events. type Event struct { // Types that are valid to be assigned to EventType: // *Event_MetaEvent @@ -539,6 +541,7 @@ func (*Event) XXX_OneofWrappers() []interface{} { } } +// MetaEvent gives general information regarding Skaffold like version info type MetaEvent struct { Entry string `protobuf:"bytes,1,opt,name=entry,proto3" json:"entry,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -578,6 +581,8 @@ func (m *MetaEvent) GetEntry() string { return "" } +// BuildEvent describes if the build status per artifact. Status could be one of +// "InProgress", "Completed" or "Failed". type BuildEvent struct { Artifact string `protobuf:"bytes,1,opt,name=artifact,proto3" json:"artifact,omitempty"` Status string `protobuf:"bytes,2,opt,name=status,proto3" json:"status,omitempty"` @@ -633,6 +638,7 @@ func (m *BuildEvent) GetErr() string { return "" } +// Deploy Event describes if the deployment has started, is in progress or is complete. type DeployEvent struct { Status string `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` Err string `protobuf:"bytes,2,opt,name=err,proto3" json:"err,omitempty"` @@ -680,6 +686,7 @@ func (m *DeployEvent) GetErr() string { return "" } +// StatusCheck Event describes if the Status check has started, is in progress, has succeeded or failed. type StatusCheckEvent struct { Status string `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` Message string `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"` @@ -798,6 +805,7 @@ func (m *ResourceStatusCheckEvent) GetErr() string { return "" } +// PortEvent Event describes each port forwarding event. type PortEvent struct { LocalPort int32 `protobuf:"varint,1,opt,name=localPort,proto3" json:"localPort,omitempty"` RemotePort int32 `protobuf:"varint,2,opt,name=remotePort,proto3" json:"remotePort,omitempty"` @@ -893,6 +901,7 @@ func (m *PortEvent) GetResourceName() string { return "" } +// FileSyncEvent describes the sync status. type FileSyncEvent struct { FileCount int32 `protobuf:"varint,1,opt,name=fileCount,proto3" json:"fileCount,omitempty"` Image string `protobuf:"bytes,2,opt,name=image,proto3" json:"image,omitempty"` @@ -956,6 +965,7 @@ func (m *FileSyncEvent) GetErr() string { return "" } +// LogEntry describes an event and a string description of the event. type LogEntry struct { Timestamp *timestamp.Timestamp `protobuf:"bytes,1,opt,name=timestamp,proto3" json:"timestamp,omitempty"` Event *Event `protobuf:"bytes,2,opt,name=event,proto3" json:"event,omitempty"` diff --git a/proto/skaffold.proto b/proto/skaffold.proto index 1995bce32d2..1d617cf88f8 100644 --- a/proto/skaffold.proto +++ b/proto/skaffold.proto @@ -17,6 +17,7 @@ message Request { string name = 1; } +// State represents the current state of the Skaffold components message State { BuildState buildState = 1; DeployState deployState = 2; @@ -48,39 +49,51 @@ message FileSyncState { string status = 1; } +// Event is one of the following events. message Event { oneof event_type { - MetaEvent metaEvent = 1; - BuildEvent buildEvent = 2; - DeployEvent deployEvent = 3; - PortEvent portEvent = 4; - StatusCheckEvent statusCheckEvent = 5; - ResourceStatusCheckEvent resourceStatusCheckEvent = 6; - FileSyncEvent fileSyncEvent = 7; + MetaEvent metaEvent = 1; // contains general information regarding Skaffold like version info + BuildEvent buildEvent = 2; // describes if the build status per artifact. Status could be one of "InProgress", "Completed" or "Failed". + DeployEvent deployEvent = 3; // describes if the deployment has started, is in progress or is complete. + PortEvent portEvent = 4; // describes each port forwarding event. + StatusCheckEvent statusCheckEvent = 5; // describes if the Status check has started, is in progress, has succeeded or failed. + ResourceStatusCheckEvent resourceStatusCheckEvent = 6; // indicates progress for each kubernetes deployment. + FileSyncEvent fileSyncEvent = 7; // describes the sync status. } } +// MetaEvent gives general information regarding Skaffold like version info message MetaEvent { string entry = 1; } +// BuildEvent describes if the build status per artifact. Status could be one of +// "InProgress", "Completed" or "Failed". message BuildEvent { - string artifact = 1; - string status = 2; - string err = 3; + string artifact = 1; // artifact name + string status = 2; // artifact build status oneof: InProgress, Completed, Failed + string err = 3; // error when build status is Failed. } +// Deploy Event describes if the deployment has started, is in progress or is complete. message DeployEvent { - string status = 1; - string err = 2; + string status = 1; // deployment status oneof: InProgress, Completed, Failed + string err = 2; // error when status is Failed } +// StatusCheck Event describes if the Status check has started, is in progress, has succeeded or failed. message StatusCheckEvent { string status = 1; string message = 2; string err = 3; } +// 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. e.g. + message ResourceStatusCheckEvent { string resource = 1; string status = 2; @@ -88,28 +101,31 @@ message ResourceStatusCheckEvent { string err = 4; } +// PortEvent Event describes each port forwarding event. message PortEvent { - int32 localPort = 1; - int32 remotePort = 2; - string podName = 3; - string containerName = 4; - string namespace = 5; + int32 localPort = 1; // local port for forwarded resource + int32 remotePort = 2; // remote port is the resource port that will be forwarded. + string podName = 3; // pod name if port forwarded resourceType is Pod + string containerName = 4; // container name if specified in the kubernetes spec + string namespace = 5; // the namespace of the resource to port forward. string portName = 6; - string resourceType=7; - string resourceName=8; + string resourceType=7; // resource type e.g. "pod", "service". + string resourceName=8; // name of the resource to forward. } +// FileSyncEvent describes the sync status. message FileSyncEvent { - int32 fileCount = 1; - string image = 2; - string status = 3; - string err = 4; + int32 fileCount = 1; // number of files synced + string image = 2; // the container image to which files are sycned. + string status = 3; // status of file sync. one of: Not Started, In progress, Succeeded, Failed. + string err = 4; // error in case of status failed. } +// LogEntry describes an event and a string description of the event. message LogEntry { - google.protobuf.Timestamp timestamp = 1; - Event event = 2; - string entry = 3; + google.protobuf.Timestamp timestamp = 1; // timestamp of the event. + Event event = 2; // Event + string entry = 3; // description of the event. } message UserIntentRequest { From adfc83df77d037bcef8fb10c584b2479deb1b884 Mon Sep 17 00:00:00 2001 From: Tejal Desai Date: Fri, 1 Nov 2019 13:38:59 -0700 Subject: [PATCH 9/9] code review comments --- .../{concepts/api/_index.md => design/api.md} | 22 +++++++++---------- docs/content/en/docs/references/_index.md | 2 +- docs/content/en/docs/references/api/_index.md | 7 +++--- proto/skaffold.pb.go | 7 +++--- proto/skaffold.proto | 7 +++--- 5 files changed, 24 insertions(+), 21 deletions(-) rename docs/content/en/docs/{concepts/api/_index.md => design/api.md} (87%) diff --git a/docs/content/en/docs/concepts/api/_index.md b/docs/content/en/docs/design/api.md similarity index 87% rename from docs/content/en/docs/concepts/api/_index.md rename to docs/content/en/docs/design/api.md index 1530aa52260..1262aaf9ac7 100644 --- a/docs/content/en/docs/concepts/api/_index.md +++ b/docs/content/en/docs/design/api.md @@ -1,20 +1,20 @@ --- title: "Skaffold API" linkTitle: "Skaffold API" -weight: 40 +weight: 60 --- When running [`skaffold dev`]({{< relref "/docs/workflows/dev" >}}) or [`skaffold debug`]({{< relref "/docs/workflows/debug" >}}), Skaffold starts a server that exposes an API over the lifetime of the Skaffold process. Besides the CLI, this API is the primary way tools like IDEs integrate with Skaffold for **retrieving information about the pipeline** and for **controlling the phases in the pipeline**. -To retrieve information of the Skaffold pipeline, the Skaffold API provides two main functionalities: +To retrieve information about the Skaffold pipeline, the Skaffold API provides two main functionalities: - * A [streaming event log]({{< relref "/docs/concepts/api#events-api">}}) created from the different phases in a pipeline run and + * A [streaming event log]({{< relref "/docs/design/api#events-api">}}) created from the different phases in a pipeline run and - * A snapshot of the [overall state]({{< relref "/docs/concepts/api#state-api" >}}) of the pipeline at any given time during the run. + * A snapshot of the [overall state]({{< relref "/docs/design/api#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/concepts/api#controlling-build-sync-deploy" >}}) +To control the individual phases of the Skaffold, the Skaffold API provides [fine grained control over]({{< relref "/docs/design/api#controlling-build-sync-deploy" >}}) the individual phases of the pipeline (build, deploy and sync). @@ -51,7 +51,7 @@ WARN[0000] port 50051 for gRPC server already in use: using 50053 instead To connect to the `gRPC` server at default port `50051` use the following code snippet. {{< alert title="Note" >}} -The skaffold gRPC server is not an HTTPS service, hence we need to specify .WithInSecure() +The skaffold gRPC server is not an HTTPS service, hence we need to specify grpc.WithInSecure() {{}} ```golang @@ -82,7 +82,7 @@ Skaffold's API exposes the three main endpoints: ### Events API -Skaffold provides a continuous development mode [`skaffold dev`]({{< relref "/docs/workflows/dev" >}}) which builds, deploys +Skaffold provides a continuous development mode [`skaffold dev`]({{< relref "/docs/workflows/dev" >}}) which rebuilds and redeploys your application on changes. In a single development loop, one or more container images may be built and deployed. @@ -93,7 +93,7 @@ Tools that integrate with Skaffold can use these events to kick-off parts of the Example scenarios: * port forwarding events are used by Cloud Code to attach debuggers automatically to running containers. -* when a port-forwarded frontend service is redeployed successfully, kick-off a suite of Selenium tests can be executed to test changes. +* when a port-forwarded frontend service is redeployed successfully, kick-off a suite of Selenium tests that test changes to the newly deployed service.. **Event API contract** @@ -110,7 +110,7 @@ Example scenarios: Using `curl` and `HTTP_RPC_PORT=50052`, an example output of a `skaffold dev` execution on our [getting-started example](https://github.com/GoogleContainerTools/skaffold/tree/master/examples/getting-started) ```bash curl localhost:50052/v1/events -{"result":{"timestamp":"2019-10-16T18:26:11.385251549Z","event":{"metaEvent":{"entry":"Starting Skaffold: \u0026{Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate:2019-10-03T15:01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"}}}} +{"result":{"timestamp":"2019-10-16T18:26:11.385251549Z","event":{"metaEvent":{"entry":"Starting Skaffold: {Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1beta15 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate:2019-10-03T15:01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"}}}} {"result":{"timestamp":"2019-10-16T18:26:11.436231589Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"In Progress"}},"entry":"Build started for artifact gcr.io/k8s-skaffold/skaffold-example"}} {"result":{"timestamp":"2019-10-16T18:26:12.010124246Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"Complete"}},"entry":"Build completed for artifact gcr.io/k8s-skaffold/skaffold-example"}} {"result":{"timestamp":"2019-10-16T18:26:12.391721823Z","event":{"deployEvent":{"status":"In Progress"}},"entry":"Deploy started"}} @@ -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/concepts/api#creating-a-grpc-client" >}}) +To get events from the `gRPC` server, first create [`gRPC` client]({{< relref "/docs/design/api#creating-a-grpc-client" >}}) ```golang func main() { @@ -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/concepts/api#creating-a-grpc-client" >}}) +To get events over `gRPC` server, first create [`gRPC` client]({{< relref "/docs/design/api#creating-a-grpc-client" >}}) ```code func main() { // Create a gRPC client connection to localhost:50051. diff --git a/docs/content/en/docs/references/_index.md b/docs/content/en/docs/references/_index.md index fe9c985c550..17a3e7e9af2 100755 --- a/docs/content/en/docs/references/_index.md +++ b/docs/content/en/docs/references/_index.md @@ -10,5 +10,5 @@ weight: 100 | [skaffold.yaml]({{< relref "/docs/references/yaml" >}}) | | [Deprecation Policy]({{< relref "/docs/references/deprecation" >}}) | | [Privacy Settings] ({{< relref "/docs/references/privacy" >}}) | -| [Skaffold API]({{< relref "/docs/references/api" >}}) | +| [API Reference]({{< relref "/docs/references/api" >}}) | diff --git a/docs/content/en/docs/references/api/_index.md b/docs/content/en/docs/references/api/_index.md index f87682710bb..6c00678b902 100644 --- a/docs/content/en/docs/references/api/_index.md +++ b/docs/content/en/docs/references/api/_index.md @@ -46,8 +46,8 @@ ### BuildEvent -BuildEvent describes if the build status per artifact. Status could be one of -"InProgress", "Completed" or "Failed". +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 | @@ -96,7 +96,8 @@ states ### DeployEvent -Deploy Event describes if the deployment has started, is in progress or is complete. +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 | diff --git a/proto/skaffold.pb.go b/proto/skaffold.pb.go index fbdbc08b4a0..dab3fd6afef 100644 --- a/proto/skaffold.pb.go +++ b/proto/skaffold.pb.go @@ -581,8 +581,8 @@ func (m *MetaEvent) GetEntry() string { return "" } -// BuildEvent describes if the build status per artifact. Status could be one of -// "InProgress", "Completed" or "Failed". +// 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. type BuildEvent struct { Artifact string `protobuf:"bytes,1,opt,name=artifact,proto3" json:"artifact,omitempty"` Status string `protobuf:"bytes,2,opt,name=status,proto3" json:"status,omitempty"` @@ -638,7 +638,8 @@ func (m *BuildEvent) GetErr() string { return "" } -// Deploy Event describes if the deployment has started, is in progress or is complete. +// DeployEvent gives the status of a deployment, and will be emitted by Skaffold +// anytime a deployment starts or completes, successfully or not. type DeployEvent struct { Status string `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` Err string `protobuf:"bytes,2,opt,name=err,proto3" json:"err,omitempty"` diff --git a/proto/skaffold.proto b/proto/skaffold.proto index 1d617cf88f8..482dd296898 100644 --- a/proto/skaffold.proto +++ b/proto/skaffold.proto @@ -67,15 +67,16 @@ message MetaEvent { string entry = 1; } -// BuildEvent describes if the build status per artifact. Status could be one of -// "InProgress", "Completed" or "Failed". +// 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. message BuildEvent { string artifact = 1; // artifact name string status = 2; // artifact build status oneof: InProgress, Completed, Failed string err = 3; // error when build status is Failed. } -// Deploy Event describes if the deployment has started, is in progress or is complete. +// DeployEvent gives the status of a deployment, and will be emitted by Skaffold +// anytime a deployment starts or completes, successfully or not. message DeployEvent { string status = 1; // deployment status oneof: InProgress, Completed, Failed string err = 2; // error when status is Failed