docs(go): add go fallback strategy troubleshooting guide (#821)
* docs(go): add go fallback strategy troubleshooting guide * docs(go): formattings
This commit is contained in:
Anna Owens
GitHub
Родитель
18ed6c4c31
Коммит
c07a28ab9f
|
|
@ -2,36 +2,43 @@
|
|||
|
||||
## Requirements
|
||||
|
||||
Go detection depends on the following to successfully run:
|
||||
Go detection runs when one of the following files is found in the project:
|
||||
|
||||
- `go.mod` or `go.sum` files
|
||||
- `go.mod` or `go.sum`
|
||||
|
||||
## Default Detection strategy
|
||||
|
||||
Go detection depends on the following to successfully run:
|
||||
Default Go detection depends on the following to successfully run:
|
||||
|
||||
- Go v1.11+.
|
||||
- Go v1.11+.
|
||||
|
||||
Full dependency graph generation is supported if Go v1.11+ is present
|
||||
on the build agent. If no Go v1.11+ is present, fallback detection
|
||||
strategy is performed.
|
||||
|
||||
Go detection is performed by parsing output from executing [go list -m
|
||||
-json all](1). To generate the graph, the command [go mod graph](2) is
|
||||
executed, this only adds edges between the components that were
|
||||
already registered by `go list`.
|
||||
Go detection is performed by parsing output from executing
|
||||
[go list -mod=readonly -m -json all](1). To generate the graph, the command
|
||||
[go mod graph](2) is executed. This only adds edges between the components
|
||||
that were already registered by `go list`.
|
||||
|
||||
## Fallback Detection strategy
|
||||
|
||||
The fallback detections trategy is known to overreport (see the
|
||||
[known limitations](#known-limitations)). Read through the
|
||||
[troubleshooting section](#troubleshooting-failures-to-run-the-default-go-detection-strategy)
|
||||
for tips on how to ensure that the newer, more accurate default
|
||||
detection strategy runs successfully.
|
||||
|
||||
To force the fallback detection strategy, set the environment
|
||||
variable: `DisableGoCliScan=true`
|
||||
|
||||
### `go.mod` before go 1.17
|
||||
|
||||
Go detection is performed by parsing any `go.mod` or `go.sum` found
|
||||
under the scan directory.
|
||||
|
||||
Only root dependency information is generated instead of full graph.
|
||||
I.e. tags the top level component or explicit dependency a given
|
||||
transitive dependency was brought by. Given a dependency tree A -> B
|
||||
-> C, C's root dependency is A.
|
||||
Only root dependency information is generated in the fallback detection
|
||||
strategy. The full graph is not detected.
|
||||
|
||||
### `go.mod` after 1.17
|
||||
|
||||
|
|
@ -41,37 +48,104 @@ dependencies, including transitive ones. [^3]
|
|||
|
||||
Similarly, no graph is generated.
|
||||
|
||||
**To force fallback detection strategy, create set environment
|
||||
variable `DisableGoCliScan=true`.**
|
||||
## Troubleshooting failures to run the default Go detection strategy
|
||||
|
||||
The fallback detection strategy is known to overreport by nature of
|
||||
parsing `go.sum` files which contain historical component information.
|
||||
|
||||
If you are experiencing overdetection from `go.sum` files or have
|
||||
otherwise been made aware that you are using the fallback Go detection
|
||||
strategy, search Component Detection output for the following to determine
|
||||
what action is needed:
|
||||
|
||||
| CD output | Solution |
|
||||
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
|
||||
| `Go CLI was not found in the system` | [Ensure that Go v1.17+ is installed](#ensure-that-go-v117-is-installed-on-the-build-agent) |
|
||||
| `#[error]Go CLI command "go list -m -json all" failed with error:` | [Resolve `go list` errors](#resolve-go-list-errors) |
|
||||
| `Go cli scan was manually disabled, fallback strategy performed.` | [Remove the `DisableGoCliScan` environment variable](#remove-the-disablegocliscan-environment-variable) |
|
||||
| _Timeouts in Go detection_ | [Fetch Go modules](#fetch-go-modules-before-the-component-detection-build-task-runs) |
|
||||
|
||||
If you do not believe that Go is used in your project but Go detection is running,
|
||||
it is likely that you need to [clean up extraneous build files](#clean-up-extraneous-build-files).
|
||||
|
||||
### Ensure that Go v1.17+ is installed on the build agent
|
||||
|
||||
Install Go CLI tools v1.17+ and ensure that it is available at the
|
||||
Component Detection step.
|
||||
|
||||
If Go CLI tools are installed in a prior build step but
|
||||
Component Detection is not finding them, ensure that they
|
||||
are not cleaned up or installed inside a container.
|
||||
|
||||
### Resolve `go list` errors.
|
||||
|
||||
Errors are logged in the Component Detection build task output and begin with
|
||||
`#[error]Go CLI command "go list -m -json all" failed with error:`. These errors
|
||||
are typically caused by version resolution problems or incorrectly formatted `go.mod`
|
||||
files.
|
||||
|
||||
### Remove the `DisableGoCliScan` environment variable
|
||||
|
||||
The variable should not be set or should be set to `false`.
|
||||
|
||||
### Fetch Go modules before the Component Detection build task runs.
|
||||
|
||||
If modules are not fetched, `go list` will pull the modules and may
|
||||
negatively impact performance at detection time.
|
||||
|
||||
If you are still experiencing timouts, the fallback strategy might be more
|
||||
appropriate for your project:
|
||||
|
||||
1. Set `DisableGoCli=true`.
|
||||
1. Run `go mod tidy` to clean your `go.mod` and `go.sum`s to reduce overreporting.
|
||||
1. Install Go v1.17+ to bypass go.sum scanning.
|
||||
|
||||
### Clean up extraneous build files
|
||||
|
||||
Go detection runs when a `go.sum` or `go.mod` file is encountered. If
|
||||
you do not use Go in your project, search for the following in Component
|
||||
Detection build output to find the paths to the Go files CD has detected.
|
||||
Component Detection must be running in debug mode to see these logs:
|
||||
|
||||
`##[debug]Found Go.mod:` or
|
||||
`##[debug]Found Go.sum:`
|
||||
|
||||
When you have found the affected files, you may:
|
||||
|
||||
1. Delete the files if they exist but are not necessary in your project.
|
||||
2. Add a clean-up step to your build to remove the files if they are
|
||||
generated prior to the Component Detection build step but are not related
|
||||
to your project.
|
||||
3. [Exclude the directory](../detector-arguments.md) if it should not be scanned by Component
|
||||
Detection.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- If the default strategy is used and go modules are not present in
|
||||
the system before the detector is executed, the go cli will fetch all
|
||||
modules to generate the dependency graph. This will incur additional
|
||||
detector time execution.
|
||||
- If the default strategy is used and go modules are not present in
|
||||
the system before the detector is executed, the go cli will fetch all
|
||||
modules to generate the dependency graph. This will incur additional
|
||||
detector time execution.
|
||||
|
||||
- Dev dependency tagging is not supported.
|
||||
- Dev dependency tagging is not supported.
|
||||
|
||||
- Go detection will fallback if no Go v1.11+ is present.
|
||||
- Go detection will fallback if no Go v1.11+ is present.
|
||||
|
||||
- (Prior to Go 1.17) Due to the nature of `go.sum` containing
|
||||
references for all dependencies, including historical,
|
||||
no-longer-needed dependencies; the fallback strategy can result in
|
||||
over detection. Executing [go mod
|
||||
tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via the
|
||||
fallback strategy is encouraged.
|
||||
- (Prior to Go 1.17) Due to the nature of `go.sum` containing
|
||||
references for all dependencies, including historical,
|
||||
no-longer-needed dependencies; the fallback strategy can result in
|
||||
over detection. Executing [go mod
|
||||
tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via the
|
||||
fallback strategy is encouraged.
|
||||
|
||||
- Some legacy dependencies may report stale transitive dependencies in
|
||||
their manifests, in this case you can remove them safely from your
|
||||
binaries by using [exclude
|
||||
directive](https://go.dev/doc/modules/gomod-ref#exclude).
|
||||
- Some legacy dependencies may report stale transitive dependencies in
|
||||
their manifests, in this case you can remove them safely from your
|
||||
binaries by using [exclude
|
||||
directive](https://go.dev/doc/modules/gomod-ref#exclude).
|
||||
|
||||
## Environment Variables
|
||||
|
||||
If the environment variable `DisableGoCliScan` is set to `true`, the
|
||||
Go detector parses `go.mod` and `go.sum` to discover dependencies.
|
||||
otherwise, it executes default strategy.
|
||||
Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy).
|
||||
|
||||
## Go Overview
|
||||
|
||||
|
|
@ -98,20 +172,20 @@ of Go's module system.[^4] It serves several crucial purposes:
|
|||
Dependencies are listed with their module paths and version
|
||||
constraints.
|
||||
|
||||
```
|
||||
go module example.com/myproject
|
||||
```
|
||||
go module example.com/myproject
|
||||
|
||||
go 1.17
|
||||
go 1.17
|
||||
|
||||
require (
|
||||
github.com/somepackage v1.2.3 golang.org/x/someotherpackage v0.4.0
|
||||
)
|
||||
require (
|
||||
github.com/somepackage v1.2.3 golang.org/x/someotherpackage v0.4.0
|
||||
)
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
Here, `github.com/somepackage` and `golang.org/x/someotherpackage`
|
||||
are declared as project dependencies with specific version
|
||||
constraints.
|
||||
Here, `github.com/somepackage` and `golang.org/x/someotherpackage`
|
||||
are declared as project dependencies with specific version
|
||||
constraints.
|
||||
|
||||
3. **Semantic Versioning**: Go uses Semantic Versioning (Semver) to
|
||||
specify version constraints for dependencies. You can specify
|
||||
|
|
@ -272,7 +346,7 @@ The main change for the go detector was not in the parsing of the
|
|||
go.mod files, but rather simply filtering `go.sum` files if an
|
||||
adjacent `go.mod` file specified a version higher than 1.17.
|
||||
|
||||
[1]: https://go.dev/ref/mod#go-list-m
|
||||
[1]: https://go.dev/ref/mod#go-list-m
|
||||
[2]: https://go.dev/ref/mod#go-mod-graph
|
||||
[3]: https://go.dev/doc/modules/gomod-ref#go-notes
|
||||
[4]: https://go.dev/doc/modules/gomod-ref
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче