doc: simplify how-to guides by coryan · Pull Request #304 · GoogleCloudPlatform/functions-framework-cpp · GitHub
Skip to content

doc: simplify how-to guides #304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
coryan merged 1 commit into from
Mar 30, 2021
Merged

doc: simplify how-to guides #304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 22 additions & 28 deletions examples/site/howto_create_container/README.md
View file
Open in desktop
66 changes: 34 additions & 32 deletions examples/site/howto_deploy_cloud_event/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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"
```

Expand Down Expand Up @@ -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
Expand All @@ -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
33 changes: 13 additions & 20 deletions examples/site/howto_deploy_to_cloud_run/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
```

Expand Down
10 changes: 5 additions & 5 deletions examples/site/howto_local_development/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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/
22 changes: 11 additions & 11 deletions examples/site/howto_offload_builder_creation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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
20 changes: 10 additions & 10 deletions examples/site/testing_pubsub/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
32 changes: 14 additions & 18 deletions examples/site/testing_storage/README.md
View file
Open in desktop