diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/development/ai_features/index.md | 59 | ||||
| -rw-r--r-- | doc/development/utilities.md | 51 | ||||
| -rw-r--r-- | doc/topics/git/index.md | 2 | ||||
| -rw-r--r-- | doc/user/application_security/container_scanning/index.md | 13 |
4 files changed, 58 insertions, 67 deletions
diff --git a/doc/development/ai_features/index.md b/doc/development/ai_features/index.md index 64a78bab7d1..34da1831770 100644 --- a/doc/development/ai_features/index.md +++ b/doc/development/ai_features/index.md @@ -268,65 +268,6 @@ I --> J[GraphqlTriggers.ai_completion_response] J --> K[::GitlabSchema.subscriptions.trigger] ``` -## CircuitBreaker - -The CircuitBreaker concern is a reusable module that you can include in any class that needs to run code with circuit breaker protection. The concern provides a `run_with_circuit` method that wraps a code block with circuit breaker functionality, which helps prevent cascading failures and improves system resilience. For more information about the circuit breaker pattern, see: - -- [What is Circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html). -- [The Hystrix documentation on CircuitBreaker](https://github.com/Netflix/Hystrix/wiki/How-it-Works#circuit-breaker). - -### Use CircuitBreaker - -To use the CircuitBreaker concern, you need to include it in a class. For example: - -```ruby -class MyService - include Gitlab::Llm::Concerns::CircuitBreaker - - def call_external_service - run_with_circuit do - # Code that interacts with external service goes here - - raise InternalServerError - end - end -end -``` - -The `call_external_service` method is an example method that interacts with an external service. -By wrapping the code that interacts with the external service with `run_with_circuit`, the method is executed within the circuit breaker. -The circuit breaker is created and configured by the `circuit` method, which is called automatically when the `CircuitBreaker` module is included. -The method should raise `InternalServerError` error which will be counted towards the error threshold if raised during the execution of the code block. - -The circuit breaker tracks the number of errors and the rate of requests, -and opens the circuit if it reaches the configured error threshold or volume threshold. -If the circuit is open, subsequent requests fail fast without executing the code block, and the circuit breaker periodically allows a small number of requests through to test the service's availability before closing the circuit again. - -### Configuration - -The circuit breaker is configured with two constants which control the number of errors and requests at which the circuit will open: - -- `ERROR_THRESHOLD` -- `VOLUME_THRESHOLD` - -You can adjust these values as needed for the specific service and usage pattern. -The `InternalServerError` is the exception class counted towards the error threshold if raised during the execution of the code block. -This is the exception class that triggers the circuit breaker when raised by the code that interacts with the external service. - -NOTE: -The `CircuitBreaker` module depends on the `Circuitbox` gem to provide the circuit breaker implementation. By default, the service name is inferred from the class name where the concern module is included. Override the `service_name` method if the name needs to be different. - -### Testing - -To test code that uses the `CircuitBreaker` concern, you can use `RSpec` shared examples and pass the `service` and `subject` variables: - -```ruby -it_behaves_like 'has circuit breaker' do - let(:service) { dummy_class.new } - let(:subject) { service.dummy_method } -end -``` - ## How to implement a new action ### Register a new method diff --git a/doc/development/utilities.md b/doc/development/utilities.md index d2d7c1a11e8..dbdf13feef8 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -284,3 +284,54 @@ end ## `ReactiveCaching` Read the documentation on [`ReactiveCaching`](reactive_caching.md). + +## `CircuitBreaker` + +The `Gitlab::CircuitBreaker` can be wrapped around any class that needs to run code with circuit breaker protection. It provides a `run_with_circuit` method that wraps a code block with circuit breaker functionality, which helps prevent cascading failures and improves system resilience. For more information about the circuit breaker pattern, see: + +- [What is Circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html). +- [The Hystrix documentation on CircuitBreaker](https://github.com/Netflix/Hystrix/wiki/How-it-Works#circuit-breaker). + +### Use CircuitBreaker + +To use the CircuitBreaker wrapper: + +```ruby +class MyService + def call_external_service + Gitlab::CircuitBreaker.run_with_circuit('ServiceName') do + # Code that interacts with external service goes here + + raise Gitlab::CircuitBreaker::InternalServerError # if there is an issue + end + end +end +``` + +The `call_external_service` method is an example method that interacts with an external service. +By wrapping the code that interacts with the external service with `run_with_circuit`, the method is executed within the circuit breaker. + +The method should raise an `InternalServerError` error, which will be counted towards the error threshold if raised during the execution of the code block. +The circuit breaker tracks the number of errors and the rate of requests, +and opens the circuit if it reaches the configured error threshold or volume threshold. +If the circuit is open, subsequent requests fail fast without executing the code block, and the circuit breaker periodically allows a small number of requests through to test the service's availability before closing the circuit again. + +### Configuration + +You need to specify a service name for each unique circuit that is used as the cache key. This should be a `CamelCase` string which identifies the circuit. + +The circuit breaker has defaults that can be overridden per circuit, for example: + +```ruby +Gitlab::CircuitBreaker.run_with_circuit('ServiceName', options = { volume_threshold: 5 }) do + ... +end +``` + +The defaults are: + +- `exceptions`: `[Gitlab::CircuitBreaker::InternalServerError]` +- `error_threshold`: `50` +- `volume_threshold`: `10` +- `sleep_window`: `90` +- `time_window`: `60` diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index e349cf0bb92..0f629abb9aa 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -38,7 +38,7 @@ appropriate for when you're ready to start learning Git by doing: - [How to install Git](how_to_install_git/index.md) - [Start using Git on the command line](../../gitlab-basics/start-using-git.md) - Tutorial: [Make your first Git commit](../../tutorials/make_first_git_commit/index.md) -- Tutorial: [How to update Git commit messages](../../tutorials/update_commit_messages/index.md) +- Tutorial: [Update Git commit messages](../../tutorials/update_commit_messages/index.md) - The [GitLab CLI](https://gitlab.com/gitlab-org/cli/) A typical Git user encounters these concepts soon after starting to use Git: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index ac03f08e23b..15b3e683e17 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -263,17 +263,16 @@ including a large number of false positives. | `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | -| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | +| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | -| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | -| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. | Trivy | | `CS_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | +| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | +| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | -| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | -| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | -| `CS_TRIVY_JAVA_DB` | `"ghcr.io/aquasecurity/trivy-java-db"` | Specify an alternate location for the [trivy-java-db](https://github.com/aquasecurity/trivy-java-db) vulnerability database. | Trivy | -| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | +| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. | Trivy || `CS_TRIVY_JAVA_DB` | `"ghcr.io/aquasecurity/trivy-java-db"` | Specify an alternate location for the [trivy-java-db](https://github.com/aquasecurity/trivy-java-db) vulnerability database. | Trivy | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. | All | ### Supported distributions |