Code reference¶

Generated from the docstrings of the app's package, app/pubgrade_sidecar.

App¶

App factory, and entry point for development.

The image serves the app with Gunicorn (pubgrade_sidecar.app:create_app(), with FOCA's settings, foca.gunicorn_config); python -m pubgrade_sidecar.app (in app/) runs it with Flask's development server.

create_app ¶

create_app() -> App

Create the app from its configuration.

Gunicorn calls this in its worker, after forking. The sidecar keeps its deliveries in memory, so it must run in a single worker process (as with FOCA's Gunicorn settings), with threads.

Returns:

Type	Description
`App`	Connexion app.

main ¶

main() -> None

Run the app with Flask's development server, on the configured port.

For development; not for production.

Controllers¶

Controllers of the API: read and update the image tags of Deployments.

getDeployment ¶

getDeployment() -> list[str]

List the deployments in the namespace.

Returns:

Type	Description
`list[str]`	Names of the deployments.

Raises:

Type	Description
`Unauthorized`	If the token is missing or wrong.
`Forbidden`	If the sidecar has no right to list the deployments.

getImage ¶

getImage(deployment_name: str) -> Response

Report the image and the rollout status of a deployment.

The record of the delivery is read before the Deployment, so that a delivery that was just patched can't be combined with an older Deployment.

Parameters:

Name	Type	Description	Default
`deployment_name`	`str`	Name of the deployment.	required

Returns:

Type	Description
`Response`	JSON response with the image and the status. The last notification
`Response`	per image repository, if any, is known until the sidecar restarts: a
`Response`	failed or waiting delivery of any of them counts over the
`Response`	Deployment's own status, a failed one first.

Raises:

Type	Description
`Unauthorized`	If the token is missing or wrong.
`NotFound`	If the deployment doesn't exist.
`Forbidden`	If the sidecar has no right to read the deployment.

deleteDeployment ¶

deleteDeployment(deployment_name: str) -> str

Delete the pod of the given name.

Parameters:

Name	Type	Description	Default
`deployment_name`	`str`	Name of the pod.	required

Returns:

Type	Description
`str`	Confirmation of the deletion.

Raises:

Type	Description
`Unauthorized`	If the token is missing or wrong.
`NotFound`	If the pod doesn't exist.
`Forbidden`	If the sidecar has no right to delete the pod.

updateDeployment ¶

updateDeployment(deployment_name: str) -> tuple[Response, int]

Accept a notification of a new image and start the delivery.

Every container of the deployment whose image repository equals the notification's changes, and only its tag. The delivery runs in the background; GET /deployment/{deployment-name} reports its state.

Parameters:

Name	Type	Description	Default
`deployment_name`	`str`	Name of the deployment.	required

Returns:

Type	Description
`Response`	JSON response with the image and status code 202, or 200 if the
`int`	deployment already uses that image: then nothing is rolled out.

Raises:

Type	Description
`Unauthorized`	If the token is missing or wrong.
`NotFound`	If the deployment doesn't exist.
`Forbidden`	If the sidecar has no right to read the deployment.
`BadRequest`	If the tag is invalid.
`ImageRepositoryMismatch`	If no container of the deployment uses the repository.

updateDeployments ¶

updateDeployments() -> tuple[Response, int]

Accept a notification of a new image for all deployments that use it.

In every deployment that the sidecar manages, every container whose image repository equals the notification's changes, and only its tag. The sidecar manages the deployments named in the environment variable TARGET_DEPLOYMENTS (comma-separated), or all in its namespace without it; with DEPLOYMENT_LABEL (key=value, or key for any value), only those with this label. Listed deployments that don't exist are skipped. Each deployment gets its own delivery, whose state GET /deployment/{deployment-name} reports.

Returns:

Type	Description
`Response`	JSON response with the name and the new image of each deployment that
`int`	rolls out, and status code 202; or, if all deployments that use the
`tuple[Response, int]`	repository already use the image, with each of them and its image,
`tuple[Response, int]`	and status code 200: then nothing is rolled out.

Raises:

Type	Description
`Unauthorized`	If the token is missing or wrong.
`BadRequest`	If the tag is invalid.
`NotFound`	If no container of these deployments uses the repository.
`Forbidden`	If the sidecar has no right to read the deployments.

check_image_availability ¶

check_image_availability(image_repo: str, tag: str = 'latest') -> bool

Check whether the registry of an image has it.

Asks the registry for the image's manifest (OCI distribution API), over HTTPS, or HTTP for the hosts in INSECURE_REGISTRIES, with a token or Basic authentication if the registry asks for it (see _head_manifest).

Parameters:

Name	Type	Description	Default
`image_repo`	`str`	Canonical repository of the image, see `_parse_image`.	required
`tag`	`str`	Tag of the image.	`'latest'`

Returns:

Type	Description
`bool`	Whether the image is available. Network and authentication errors
`bool`	count as not available.

Errors¶

Errors of the API and the responses that FOCA returns for them.

ImageUnavailable ¶

Bases: NotFound

Raised when the image of a notification isn't in its registry.

Only raised in the background, while a delivery waits for the image, so never returned to clients.

ImageRepositoryMismatch ¶

Bases: Conflict

Raised when a notification is for another image repository.