Skip to content

Commit

Permalink
adds reviewers feedback
Browse files Browse the repository at this point in the history
Signed-off-by: Hanan Younes <[email protected]>
  • Loading branch information
hyounes4560 committed Nov 13, 2024
1 parent 4178e77 commit ea3553a
Show file tree
Hide file tree
Showing 5 changed files with 63 additions and 29 deletions.
33 changes: 21 additions & 12 deletions content/docs/for-app-developers/concepts/experimental-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,34 @@ title="What are experimental features?"
weight=8
+++

Certain features are considered `experimental` and susceptible to change in a future API version.
Certain features are considered `experimental` and susceptible to change in future API versions.

Check warning on line 6 in content/docs/for-app-developers/concepts/experimental-features.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Passive] In general, use active voice instead of passive voice ('are considered'). Raw Output: {"message": "[Google.Passive] In general, use active voice instead of passive voice ('are considered').", "location": {"path": "content/docs/for-app-developers/concepts/experimental-features.md", "range": {"start": {"line": 6, "column": 18}}}, "severity": "INFO"}

<!--more-->

This means users will need to enable the `experimental` mode in order to use one of these features.

Check warning on line 10 in content/docs/for-app-developers/concepts/experimental-features.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Will] Avoid using 'will'. Raw Output: {"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "content/docs/for-app-developers/concepts/experimental-features.md", "range": {"start": {"line": 10, "column": 18}}}, "severity": "WARNING"}

Check warning on line 10 in content/docs/for-app-developers/concepts/experimental-features.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.WordList] Use 'to' instead of 'in order to'. Raw Output: {"message": "[Google.WordList] Use 'to' instead of 'in order to'.", "location": {"path": "content/docs/for-app-developers/concepts/experimental-features.md", "range": {"start": {"line": 10, "column": 62}}}, "severity": "WARNING"}

To enable these features, run `pack config experimental true`, or add `experimental = true` to the `~/.pack/config.toml` file.
If using `pack`, run `pack config experimental true`, or add `experimental = true` to your `~/.pack/config.toml` file to enable experimental features.

For example, exporting your application to disk in `OCI` layout format is an experimental feature available on `pack` since version `v0.30.0`.
If using the `lifecycle` directly, set the `CNB_EXPERIMENTAL_MODE` [environment variable](https://github.com/buildpacks/spec/blob/main/platform.md#experimental-features).

The following is a list of experimental features:
The following features are experimental for `pack`:

* Image extensions
* Windows extensions
* Windows containers
* Windows buildpackage
* Buildpack registry
* Flattening a buildpack package
* building for [Windows containers][windows]
* exporting to [OCI layout][oci-layout] format on disk

Check warning on line 19 in content/docs/for-app-developers/concepts/experimental-features.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Acronyms] Spell out 'OCI', if it's unfamiliar to the audience. Raw Output: {"message": "[Google.Acronyms] Spell out 'OCI', if it's unfamiliar to the audience.", "location": {"path": "content/docs/for-app-developers/concepts/experimental-features.md", "range": {"start": {"line": 19, "column": 17}}}, "severity": "INFO"}
* Interacting with the [buildpack registry][registry]
* `pack manifest` commands
* `pack buildpack --flatten`
* `pack build --interactive`
* When building, reading project metadata version & source URL from [project.toml][project-descriptor]

For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][exp-feature].
The following features are experimental for `lifecycle`:

[exp-feature]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/export-to-oci-layout/
* Building for [Windows containers][windows]
* Exporting to [OCI layout][oci-layout] format on disk

Check warning on line 29 in content/docs/for-app-developers/concepts/experimental-features.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Acronyms] Spell out 'OCI', if it's unfamiliar to the audience. Raw Output: {"message": "[Google.Acronyms] Spell out 'OCI', if it's unfamiliar to the audience.", "location": {"path": "content/docs/for-app-developers/concepts/experimental-features.md", "range": {"start": {"line": 29, "column": 17}}}, "severity": "INFO"}

For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][oci-layout].

Check warning on line 31 in content/docs/for-app-developers/concepts/experimental-features.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Acronyms] Spell out 'OCI', if it's unfamiliar to the audience. Raw Output: {"message": "[Google.Acronyms] Spell out 'OCI', if it's unfamiliar to the audience.", "location": {"path": "content/docs/for-app-developers/concepts/experimental-features.md", "range": {"start": {"line": 31, "column": 94}}}, "severity": "INFO"}

[oci-layout]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/export-to-oci-layout/
[project-descriptor]: https://buildpacks.io/docs/reference/config/project-descriptor/
[registry]: https://buildpacks.io/docs/for-buildpack-authors/how-to/distribute-buildpacks/publish-buildpack/
[windows]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/build-for-windows/
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,15 @@ weight=99
summary="Buildpacks can define multiple processes for an application image. Specify which process should be the default."
+++

Buildpacks usually define the default process type for an application, while retaining the ability for a user to specify their desired default process.
While buildpacks usually define the default process type for an application, end users may specify the desired default process.

To configure the `build` to work differently from the default behavior:
To specify the default process:

* You first need to know what processes would be contributed by the buildpacks running in your build.
* Once known, you can append the following flag to the `pack build` command
* You first need to know what named process types might be contributed by the buildpacks in your build; for more information, see docs for [running the application][Run the application]
* Append the following flag to the `pack build` command:

```bash
pack build --default-process <process name> <image name>` # <process name> must be a valid process name in launch.toml
pack build --default-process <process name> <image name>` # <process name> must be a valid process name
```

If this flag is not provided by the user, `pack` will provide the process type as `web` to the `lifecycle`.

>As an app developer, you can specify the default process for an application. However, buildpacks-built images can contain multiple process types, to see how to invoke each one, see the [Run the application] page.

[Run the application]: https://buildpacks.io/docs/for-app-developers/how-to/build-outputs/specify-launch-process/
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Information includes:
* Whether the run-image can be rebased with a new version through the `Rebasable` label or not
* And more...!

`Pack` offers a built-in command to help you inspect the resultant image and view some of its contents as shown below:
`pack` offers a command to help you inspect the application image and view some of its contents as shown below:

Check warning on line 18 in content/docs/for-app-developers/how-to/build-outputs/inspect-app.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.WordList] Use 'app' instead of 'application'. Raw Output: {"message": "[Google.WordList] Use 'app' instead of 'application'.", "location": {"path": "content/docs/for-app-developers/how-to/build-outputs/inspect-app.md", "range": {"start": {"line": 18, "column": 49}}}, "severity": "WARNING"}

```bash
pack inspect-image test-node-js-app
Expand All @@ -39,13 +39,13 @@ Processes:

Apart from the above standard metadata, buildpacks can also populate information about the dependencies they have provided in form of a `Software Bill-of-Materials` or [SBOM].

As already mentioned, buildpacks help you get an `OCI` images that are constructed in a way that’s easy to understand and update with each of the layers being meaningful and independent of all other layers. You can get more details about each layer and how it was created to better understand how the [Build] actually worked.
Buildpacks-built images are constructed in a way that’s easy to understand, with each of the layers being meaningful and independent of all other layers. You can get more details about each layer and how it was created to better understand how the [build] actually worked.

Check warning on line 42 in content/docs/for-app-developers/how-to/build-outputs/inspect-app.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Passive] In general, use active voice instead of passive voice ('are constructed'). Raw Output: {"message": "[Google.Passive] In general, use active voice instead of passive voice ('are constructed').", "location": {"path": "content/docs/for-app-developers/how-to/build-outputs/inspect-app.md", "range": {"start": {"line": 42, "column": 25}}}, "severity": "INFO"}

There are some available tools that help you achieve this and understand what is contained in your `OCI` image; a popular one is [Dive].
There are a number of available tools that can help you achieve this and understand what is contained in your `OCI` image; a popular one is [dive].

Dive can help you inspect `OCI` images, view their layers and each layer's details. If you were to build an `OCI` image following the [multi process app] example and run `Dive` on the generated image, you'll be presented with some detailed information about all of the image layers and understand what is in each layer.
`Dive` can help you inspect `OCI` images and view their layers and each layer's details. If you were to build an `OCI` image following the [multi process app] example and run `dive` on the generated image, you'll be presented with some detailed information about all of the image layers and the contents of each layer.

You can use `Dive` as follows:
You can use `dive` as follows:

```bash
dive multi-process-app
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ docker run --rm -p 8080:8080 multi-process-app
```
<!--+- "{{execute}}"+-->

>As an app developer, you can specify what the default process is, see [specify default launch process][default-process] page for more information.
>As an app developer, you can specify what the default process is; see the [specify default launch process][default-process] page for more information.
#### Default process type with additional arguments

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,35 @@ weight=99
summary="How to troubleshoot when things go wrong."
+++

While `Buildpacks` help developers transform applications' source code into container images that can run on any cloud, creating an error-free experience remains far from achieved.
While `Buildpacks` help developers transform source code into container images that can run on any cloud, creating an error-free experience remains far from achieved.

This guide explores some of the most common issues that may prevent image build completion and provides troubleshooting tips to help end-users navigate these issues.
This guide catalogs some commonly reported issues that may prevent image build completion and provides troubleshooting tips to help end-users navigate these issues.

If you would like to report an issue, please open a PR against this page using the included template (see bottom of page in Markdown).

Check warning on line 11 in content/docs/for-app-developers/how-to/build-outputs/understand-failures.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.Parens] Use parentheses judiciously. Raw Output: {"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "content/docs/for-app-developers/how-to/build-outputs/understand-failures.md", "range": {"start": {"line": 11, "column": 102}}}, "severity": "INFO"}

#### Issue: `ERROR: failed to build: failed to fetch base layers: saving image with ID "sha256:<sha256>" from the docker daemon: Error response from daemon: unable to create manifests file: NotFound: content digest sha256:<sha256>: not found`

**Occurs when**: building and saving to a docker daemon
**Analysis**: this seems to indicate a problem with the underlying image store in `Docker`
**Remediation**: remove existing images with `docker image prune` (potentially, from multiple storage drivers if switching between `overlay2` and `containerd`)
**Related error messages**:

* `ERROR: failed to initialize analyzer: getting previous image: get history for image "test": Error response from daemon: NotFound: snapshot sha256:<sha256> does not exist: not found`
* `ERROR: failed to export: saving image: failed to fetch base layers: open /tmp/imgutil.local.image.<identifier>/blobs/sha256/<sha256>: no such file or directory`

**For more information**:

* [Issue link on GitHub](https://github.com/buildpacks/pack/issues/2270)
* [Slack thread](https://cloud-native.slack.com/archives/C0331B61A1Y/p1717422902392339?thread_ts=1717185700.984459&cid=C0331B61A1Y)
* [Another Slack thread](https://cloud-native.slack.com/archives/C033DV8D9FB/p1730243369203799)

<!--
#### Issue: `<error text>`
**Occurs when**: <creating a builder, building, running the application, etc.>
**Analysis**: < why this issue occurs >
**Remediation**: < how to avoid this issue >
**Related error messages**:
* `<error text>`
**For more information**:
* <link to GitHub issue, Slack thread, etc.>
--->

0 comments on commit ea3553a

Please sign in to comment.