From 2e2d898356ad63cfb8d7aa297c222b25fbfc38dc Mon Sep 17 00:00:00 2001 From: Carlos O'Ryan Date: Tue, 30 Mar 2021 15:28:57 +0000 Subject: [PATCH] doc: simplify how-to guides --- .../site/howto_create_container/README.md | 50 +++++++------- .../site/howto_deploy_cloud_event/README.md | 66 ++++++++++--------- .../site/howto_deploy_to_cloud_run/README.md | 33 ++++------ .../site/howto_local_development/README.md | 10 +-- .../howto_offload_builder_creation/README.md | 22 +++---- examples/site/testing_pubsub/README.md | 20 +++--- examples/site/testing_storage/README.md | 32 ++++----- 7 files changed, 109 insertions(+), 124 deletions(-) diff --git a/examples/site/howto_create_container/README.md b/examples/site/howto_create_container/README.md index 8d356568..9b03efcb 100644 --- a/examples/site/howto_create_container/README.md +++ b/examples/site/howto_create_container/README.md @@ -1,13 +1,5 @@ # How-to Guide: Running your function as Docker container -[repository-gh]: https://github.com/GoogleCloudPlatform/functions-framework-cpp -[buildpacks]: https://buildpacks.io -[docker]: https://docker.com/ -[docker-install]: https://store.docker.com/search?type=edition&offering=community -[sudoless docker]: https://docs.docker.com/engine/install/linux-postinstall/ -[pack-install]: https://buildpacks.io/docs/install-pack/ -[hello-world-http]: /examples/site/hello_world_http/hello_world_http.cc - This guide shows you how to create a container image for an example function, and how to run said image in a local container on your workstation. @@ -75,30 +67,23 @@ clone: cd $HOME/functions-framework-cpp ``` -## Setting up the buildpacks builder - -We will be using a [buildpacks][buildpacks] builder to create the container -image deployed to Cloud Run. The first time your run these commands it can take -several minutes, maybe as long as an hour, depending on your workstation's -performance. - -```sh -docker build -t gcf-cpp-run-image --target gcf-cpp-runtime -f build_scripts/Dockerfile build_scripts -docker build -t gcf-cpp-build-image --target gcf-cpp-develop -f build_scripts/Dockerfile . -pack builder create gcf-cpp-builder:bionic --config pack/builder.toml -pack config trusted-builders add gcf-cpp-builder:bionic -pack config default-builder gcf-cpp-builder:bionic -``` - ## Building a Docker image -Build a Docker image from your function using this buildpack: +> :warning: This will automatically download and compile the functions +> framework and all its dependencies. Consequently, the first build of a +> function may take several minutes (and up to an hour) depending on the +> performance of your workstation. Subsequent builds cache many binary +> artifacts, but these caches are *not* shared across functions, so plan +> accordingly. + +We use the [Google Cloud buildpack] builder to create the Docker image +containing your function: ```shell pack build \ - --builder gcf-cpp-builder:bionic \ - --env FUNCTION_SIGNATURE_TYPE=http \ - --env TARGET_FUNCTION=hello_world_http \ + --builder gcr.io/buildpacks/builder:latest \ + --env GOOGLE_FUNCTION_SIGNATURE_TYPE=http \ + --env GOOGLE_FUNCTION_TARGET=hello_world_http \ --path examples/site/hello_world_http \ gcf-cpp-hello-world-http ``` @@ -133,4 +118,13 @@ And delete the local image: ```shell docker image rm gcf-cpp-hello-world-http -``` \ No newline at end of file +``` + +[repository-gh]: https://github.com/GoogleCloudPlatform/functions-framework-cpp +[buildpacks]: https://buildpacks.io +[docker]: https://docker.com/ +[docker-install]: https://store.docker.com/search?type=edition&offering=community +[sudoless docker]: https://docs.docker.com/engine/install/linux-postinstall/ +[pack-install]: https://buildpacks.io/docs/install-pack/ +[hello-world-http]: /examples/site/hello_world_http/hello_world_http.cc +[Google Cloud buildpack]: https://github.com/GoogleCloudPlatform/buildpacks diff --git a/examples/site/howto_deploy_cloud_event/README.md b/examples/site/howto_deploy_cloud_event/README.md index c8af84ae..3d55f969 100644 --- a/examples/site/howto_deploy_cloud_event/README.md +++ b/examples/site/howto_deploy_cloud_event/README.md @@ -1,17 +1,5 @@ # How-to Guide: Deploy a C++ Pub/Sub function to Cloud Run -[repository-gh]: https://github.com/GoogleCloudPlatform/functions-framework-cpp -[howto-create-container]: /examples/site/howto_create_container/README.md -[cloud-run-quickstarts]: https://cloud.google.com/run/docs/quickstarts -[gcp-quickstarts]: https://cloud.google.com/resource-manager/docs/creating-managing-projects -[buildpacks]: https://buildpacks.io -[docker]: https://docker.com/ -[docker-install]: https://store.docker.com/search?type=edition&offering=community -[sudoless docker]: https://docs.docker.com/engine/install/linux-postinstall/ -[pack-install]: https://buildpacks.io/docs/install-pack/ -[hello-world-pubsub]: /examples/site/hello_world_pubsub/hello_world_pubsub.cc -[gcloud-eventarc-create]: https://cloud.google.com/sdk/gcloud/reference/beta/eventarc/triggers/create - ## Pre-requisites This guide assumes you are familiar with Google Cloud, and that you have a GCP @@ -79,33 +67,26 @@ clone: cd $HOME/functions-framework-cpp ``` -## Setting up the buildpacks builder - -We will be using a [buildpacks][buildpacks] builder to create the container -image deployed to Cloud Run. The first time your run these commands it can take -several minutes, maybe as long as an hour, depending on your workstation's -performance. - -```sh -docker build -t gcf-cpp-run-image --target gcf-cpp-runtime -f build_scripts/Dockerfile build_scripts -docker build -t gcf-cpp-build-image --target gcf-cpp-develop -f build_scripts/Dockerfile . -pack builder create gcf-cpp-builder:bionic --config pack/builder.toml -pack config trusted-builders add gcf-cpp-builder:bionic -pack config default-builder gcf-cpp-builder:bionic -``` - ## Building a Docker image +> :warning: This will automatically download and compile the functions +> framework and all its dependencies. Consequently, the first build of a +> function may take several minutes (and up to an hour) depending on the +> performance of your workstation. Subsequent builds cache many binary +> artifacts, but these caches are *not* shared across functions, so plan +> accordingly. + Set the `GOOGLE_CLOUD_PROJECT` shell variable to the project id of your GCP -project, and create a docker image with your function: +project, and use the [Google Cloud buildpack] builder to create a docker image +containing your function: ```shell GOOGLE_CLOUD_PROJECT=... # put the right value here pack build \ - --builder gcf-cpp-builder:bionic \ - --env FUNCTION_SIGNATURE_TYPE=cloudevent \ - --env TARGET_FUNCTION=hello_world_pubsub \ - --path examples/site/hello_world_pubsub \ + --builder gcr.io/buildpacks/builder:latest \ + --env GOOGLE_FUNCTION_SIGNATURE_TYPE=cloudevent \ + --env GOOGLE_FUNCTION_TARGET=hello_world_pubsub \ + --path examples/site/hello_world_pubsub \ "gcr.io/${GOOGLE_CLOUD_PROJECT}/gcf-cpp-hello-world-pubsub" ``` @@ -193,6 +174,14 @@ gcloud logging read \ ## Cleanup +Delete the trigger: + +```shell +gcloud beta eventarc triggers delete gcf-cpp-hello-world-pubsub-trigger \ + --project="${GOOGLE_CLOUD_PROJECT}" \ + --location="us-central1" +``` + Delete the Cloud Run deployment: ```sh @@ -208,3 +197,16 @@ And the container image: gcloud container images delete \ "gcr.io/${GOOGLE_CLOUD_PROJECT}/gcf-cpp-hello-world-pubsub:latest" ``` + +[repository-gh]: https://github.com/GoogleCloudPlatform/functions-framework-cpp +[howto-create-container]: /examples/site/howto_create_container/README.md +[cloud-run-quickstarts]: https://cloud.google.com/run/docs/quickstarts +[gcp-quickstarts]: https://cloud.google.com/resource-manager/docs/creating-managing-projects +[buildpacks]: https://buildpacks.io +[docker]: https://docker.com/ +[docker-install]: https://store.docker.com/search?type=edition&offering=community +[sudoless docker]: https://docs.docker.com/engine/install/linux-postinstall/ +[pack-install]: https://buildpacks.io/docs/install-pack/ +[hello-world-pubsub]: /examples/site/hello_world_pubsub/hello_world_pubsub.cc +[gcloud-eventarc-create]: https://cloud.google.com/sdk/gcloud/reference/beta/eventarc/triggers/create +[Google Cloud buildpack]: https://github.com/GoogleCloudPlatform/buildpacks diff --git a/examples/site/howto_deploy_to_cloud_run/README.md b/examples/site/howto_deploy_to_cloud_run/README.md index 4f1191fd..41f7160c 100644 --- a/examples/site/howto_deploy_to_cloud_run/README.md +++ b/examples/site/howto_deploy_to_cloud_run/README.md @@ -81,33 +81,26 @@ clone: cd $HOME/functions-framework-cpp ``` -## Setting up the buildpacks builder - -We will be using a [buildpacks][buildpacks] builder to create the container -image deployed to Cloud Run. The first time your run these commands it can take -several minutes, maybe as long as an hour, depending on your workstation's -performance. - -```sh -docker build -t gcf-cpp-run-image --target gcf-cpp-runtime -f build_scripts/Dockerfile build_scripts -docker build -t gcf-cpp-build-image --target gcf-cpp-develop -f build_scripts/Dockerfile . -pack builder create gcf-cpp-builder:bionic --config pack/builder.toml -pack config trusted-builders add gcf-cpp-builder:bionic -pack config default-builder gcf-cpp-builder:bionic -``` - ## Building a Docker image +> :warning: This will automatically download and compile the functions +> framework and all its dependencies. Consequently, the first build of a +> function may take several minutes (and up to an hour) depending on the +> performance of your workstation. Subsequent builds cache many binary +> artifacts, but these caches are *not* shared across functions, so plan +> accordingly. + Set the `GOOGLE_CLOUD_PROJECT` shell variable to the project id of your GCP -project, and create a docker image with your function: +project, and use the [Google Cloud buildpack] builder to create a docker image +containing your function: ```shell GOOGLE_CLOUD_PROJECT=... # put the right value here pack build \ - --builder gcf-cpp-builder:bionic \ - --env FUNCTION_SIGNATURE_TYPE=http \ - --env TARGET_FUNCTION=hello_world_http \ - --path examples/site/hello_world_http \ + --builder gcr.io/buildpacks/builder:latest \ + --env GOOGLE_FUNCTION_SIGNATURE_TYPE=http \ + --env GOOGLE_FUNCTION_TARGET=hello_world_http \ + --path examples/site/hello_world_http \ "gcr.io/${GOOGLE_CLOUD_PROJECT}/gcf-cpp-hello-world-http" ``` diff --git a/examples/site/howto_local_development/README.md b/examples/site/howto_local_development/README.md index 5841ead8..2e8de3e3 100644 --- a/examples/site/howto_local_development/README.md +++ b/examples/site/howto_local_development/README.md @@ -1,10 +1,5 @@ # How-to Guide: Local Development -[vcpkg-gh]: https://github.com/microsoft/vcpkg -[vcpkg-install]: https://github.com/microsoft/vcpkg#getting-started -[cmake]: https://cmake.org -[cmake-install]: https://cmake.org/install/ - This guide describes how to compile and run a function locally. This can be useful when writing unit test, or to accelerate the edit -> compile -> test cycle. @@ -134,3 +129,8 @@ curl http://localhost:8080 ``` You can just interrupt (`Ctrl-C`) the program to terminate it. + +[vcpkg-gh]: https://github.com/microsoft/vcpkg +[vcpkg-install]: https://github.com/microsoft/vcpkg#getting-started +[cmake]: https://cmake.org +[cmake-install]: https://cmake.org/install/ diff --git a/examples/site/howto_offload_builder_creation/README.md b/examples/site/howto_offload_builder_creation/README.md index 0c8b82d1..b5ea56b4 100644 --- a/examples/site/howto_offload_builder_creation/README.md +++ b/examples/site/howto_offload_builder_creation/README.md @@ -1,16 +1,5 @@ # How-to Guide: Use Cloud Build to create a buildpacks builder -[repository-gh]: https://github.com/GoogleCloudPlatform/functions-framework-cpp -[cloud-build-quickstarts]: https://cloud.google.com/build/docs/quickstarts -[gcp-quickstarts]: https://cloud.google.com/resource-manager/docs/creating-managing-projects -[buildpacks]: https://buildpacks.io -[docker]: https://docker.com/ -[docker-install]: https://store.docker.com/search?type=edition&offering=community -[sudoless docker]: https://docs.docker.com/engine/install/linux-postinstall/ -[pack-install]: https://buildpacks.io/docs/install-pack/ -[hello-world-http]: /examples/site/hello_world_http/hello_world_http.cc -[cloud-build]: https://cloud.google.com/cloud-build - This guide shows you how to use [Cloud Build][cloud-build] to offload the creation of [buildpacks] builders. @@ -145,3 +134,14 @@ for image in \ xargs gcloud container images delete --force-delete-tags done ``` + +[repository-gh]: https://github.com/GoogleCloudPlatform/functions-framework-cpp +[cloud-build-quickstarts]: https://cloud.google.com/build/docs/quickstarts +[gcp-quickstarts]: https://cloud.google.com/resource-manager/docs/creating-managing-projects +[buildpacks]: https://buildpacks.io +[docker]: https://docker.com/ +[docker-install]: https://store.docker.com/search?type=edition&offering=community +[sudoless docker]: https://docs.docker.com/engine/install/linux-postinstall/ +[pack-install]: https://buildpacks.io/docs/install-pack/ +[hello-world-http]: /examples/site/hello_world_http/hello_world_http.cc +[cloud-build]: https://cloud.google.com/cloud-build diff --git a/examples/site/testing_pubsub/README.md b/examples/site/testing_pubsub/README.md index a6d722ae..62b80992 100644 --- a/examples/site/testing_pubsub/README.md +++ b/examples/site/testing_pubsub/README.md @@ -1,15 +1,5 @@ # How-to Guide: Testing Event-driven Functions (Pub/Sub triggered) -[buildpacks]: https://buildpacks.io -[boost-log-gh]: https://github.com/boostorg/log -[/examples/site/hello_world_pubsub/hello_world_pubsub.cc]: /examples/site/hello_world_pubsub/hello_world_pubsub.cc -[pubsub_unit_test.cc]: pubsub_unit_test.cc -[pubsub_integration_server.cc]: pubsub_integration_server.cc -[pubsub_integration_test.cc]: pubsub_integration_test.cc -[quickstart-guide]: /examples/site/howto_local_development/README.md -[container-guide]: /examples/site/howto_create_container/README.md -[pubsub-quickstart]: https://cloud.google.com/pubsub/docs/quickstart-console - Event-driven functions do not return values, their only observable behavior are side-effects. All tests, therefore, are looking at the side-effects of these functions. Depending on where the function is deployed this might be more or @@ -117,3 +107,13 @@ env "GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}" \ "SERVICE_ID=gcf-hello-world-pubsub" \ ./pubsub_system_test # use actual path to binary ``` + +[buildpacks]: https://buildpacks.io +[boost-log-gh]: https://github.com/boostorg/log +[/examples/site/hello_world_pubsub/hello_world_pubsub.cc]: /examples/site/hello_world_pubsub/hello_world_pubsub.cc +[pubsub_unit_test.cc]: pubsub_unit_test.cc +[pubsub_integration_server.cc]: pubsub_integration_server.cc +[pubsub_integration_test.cc]: pubsub_integration_test.cc +[quickstart-guide]: /examples/site/howto_local_development/README.md +[container-guide]: /examples/site/howto_create_container/README.md +[pubsub-quickstart]: https://cloud.google.com/pubsub/docs/quickstart-console diff --git a/examples/site/testing_storage/README.md b/examples/site/testing_storage/README.md index da594578..fa81ff06 100644 --- a/examples/site/testing_storage/README.md +++ b/examples/site/testing_storage/README.md @@ -1,18 +1,4 @@ -# How-to Guide: Testing Event-driven Functions (Cloud Audit Log triggered) - -> :warning: this example depends on features in the upcoming release 0.4.0. -> until that release is cut, the default builders will link against 0.3.0 -> and this example will not work correctly. - -[buildpacks]: https://buildpacks.io -[boost-log-gh]: https://github.com/boostorg/log -[/examples/site/hello_world_storage/hello_world_storage.cc]: /examples/site/hello_world_storage/hello_world_storage.cc -[storage_unit_test.cc]: storage_unit_test.cc -[storage_integration_server.cc]: storage_integration_server.cc -[storage_integration_test.cc]: storage_integration_test.cc -[quickstart-guide]: /examples/site/howto_local_development/README.md -[container-guide]: /examples/site/howto_create_container/README.md -[pubsub-quickstart]: https://cloud.google.com/pubsub/docs/quickstart-console +# How-to Guide: Testing Event-driven Functions Event-driven functions do not return values, therefore, their only observable behavior are their side-effects and any testing for them is based in observing @@ -75,9 +61,9 @@ We will create a container for the storage "hello world" function as usual: ```shell pack build \ - --builder gcf-cpp-builder:bionic \ - --env "FUNCTION_SIGNATURE_TYPE=cloudevent" \ - --env "TARGET_FUNCTION=hello_world_storage" \ + --builder gcr.io/buildpacks/builder:latest \ + --env "GOOGLE_FUNCTION_SIGNATURE_TYPE=cloudevent" \ + --env "GOOGLE_FUNCTION_TARGET=hello_world_storage" \ --path "examples/site/hello_world_storage" \ "gcr.io/${GOOGLE_CLOUD_PROJECT}/gcf-hello-world-storage" ``` @@ -144,3 +130,13 @@ gcloud run services delete gcf-cpp-hello-world-storage \ gcloud container images delete \ "gcr.io/${GOOGLE_CLOUD_PROJECT}/gcf-cpp-hello-world-storage:latest" ``` + +[buildpacks]: https://buildpacks.io +[boost-log-gh]: https://github.com/boostorg/log +[/examples/site/hello_world_storage/hello_world_storage.cc]: /examples/site/hello_world_storage/hello_world_storage.cc +[storage_unit_test.cc]: storage_unit_test.cc +[storage_integration_server.cc]: storage_integration_server.cc +[storage_integration_test.cc]: storage_integration_test.cc +[quickstart-guide]: /examples/site/howto_local_development/README.md +[container-guide]: /examples/site/howto_create_container/README.md +[pubsub-quickstart]: https://cloud.google.com/pubsub/docs/quickstart-console