From b81383bcf170143b55e920100e3d1735d045ae63 Mon Sep 17 00:00:00 2001 From: bnechyporenko Date: Wed, 31 Jan 2024 08:09:07 +0100 Subject: [PATCH 1/6] BEP: Scaffolder task idempotency Signed-off-by: bnechyporenko --- .../README.md | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 beps/0004-scaffolder-task-idempotency/README.md diff --git a/beps/0004-scaffolder-task-idempotency/README.md b/beps/0004-scaffolder-task-idempotency/README.md new file mode 100644 index 0000000000..47d2351189 --- /dev/null +++ b/beps/0004-scaffolder-task-idempotency/README.md @@ -0,0 +1,104 @@ +--- +title: Scaffolder Task Idempotency +status: provisional +authors: + - 'benjaminl@spotify.com' + - 'patriko@spotify.com' + - 'freben@gmail.com' + - 'bnechyporenko@bol.com' +owners: +project-areas: + - scaffolder +creation-date: 2024-01-31 +--- + + + +# BEP: + + + +[**Discussion Issue**](https://github.com/backstage/backstage/issues/22590) + +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) +- [Design Details](#design-details) +- [Release Plan](#release-plan) +- [Dependencies](#dependencies) +- [Alternatives](#alternatives) + +## Summary + +Scaffolder task idempotency provides the means to make each action of the task idempotent. By default, an action is not considered to be idempotent. +It has to be crafted to a solution when action can be re-run multiple times and giving the same effect as it had been run only once. + +## Motivation + +The aim is to make task engine more reliable in terms of system crash or redeployment. If the task engine is in process of executing +tasks and system stops, after restart task engine will restore all such tasks and continue their execution. +Another purpose is to make it possible to manually retry the task from the last failed step. + +### Goals + + + +- provide a checkpoint functionality which can be used in task actions +- make built-in actions idempotent +- enhance task UI with a possibility to retry the failed task from the last failed step +- preserve a workspace till task succeeded or archived + +### Non-Goals + + + +## Proposal + + + +## Design Details + + + +## Release Plan + + + +## Dependencies + + + +## Alternatives + + From 7c07dafc1555093f9667208ed11e2867366219a4 Mon Sep 17 00:00:00 2001 From: bnechyporenko Date: Wed, 31 Jan 2024 18:43:34 +0100 Subject: [PATCH 2/6] wip Signed-off-by: bnechyporenko --- .../README.md | 122 +++++++++++++++++- 1 file changed, 116 insertions(+), 6 deletions(-) diff --git a/beps/0004-scaffolder-task-idempotency/README.md b/beps/0004-scaffolder-task-idempotency/README.md index 47d2351189..2d811d2d32 100644 --- a/beps/0004-scaffolder-task-idempotency/README.md +++ b/beps/0004-scaffolder-task-idempotency/README.md @@ -1,5 +1,5 @@ --- -title: Scaffolder Task Idempotency +title: Scaffolder Retryable Tasks status: provisional authors: - 'benjaminl@spotify.com' @@ -36,7 +36,7 @@ When editing BEPs, aim for tightly-scoped, single-topic PRs to keep discussions ## Summary -Scaffolder task idempotency provides the means to make each action of the task idempotent. By default, an action is not considered to be idempotent. +Scaffolder retriable task idempotency provides the means to make each action of the task idempotent. By default, an action is not considered to be idempotent. It has to be crafted to a solution when action can be re-run multiple times and giving the same effect as it had been run only once. ## Motivation @@ -52,10 +52,12 @@ List the specific goals of the BEP. What is it trying to achieve? How will we know that this has succeeded? --> -- provide a checkpoint functionality which can be used in task actions -- make built-in actions idempotent -- enhance task UI with a possibility to retry the failed task from the last failed step -- preserve a workspace till task succeeded or archived +- we will provide extended task API in scaffolder with a necessary tools to let tasks implement retries +- make built-in actions retryable +- enable the user to retry the failed task +- should be possible to retry the task on a different scaffolder instance +- we would like to retry from any state and not tearing down or overwriting what was created before. +- we would like to be resilient to upstream failures, i.e. a request to create a remote repository failed and repository was created, it should be handled gracefully. ### Non-Goals @@ -64,6 +66,8 @@ What is out of scope for this BEP? Listing non-goals helps to focus discussion and make progress. --> +We will not aim to magically provide idempotency for actions, it has to be explicitly implemented. + ## Proposal +We believe that idempotency is the best way to do it. Idempotency allows to rerun the actions multiple times to gracefully deal with semi-complete actions. + +### Idempotency + +### Serialization of workspace + +### Secrets + ## Design Details +### Idempotency + +This is a simplified idempotent version of GitHub repository creation action: + +```typescript + export function createGithubRepoCreateAction(options: { + integrations: ScmIntegrationRegistry; + githubCredentialsProvider?: GithubCredentialsProvider; +}) { + const {integrations, githubCredentialsProvider} = options; + + return createTemplateAction<{ + repoUrl: string; + secrets?: { [key: string]: string }; + token?: string; + }>({ + id: 'github:repo:create', + description: 'Creates a GitHub repository.', + examples, + schema: { + input: { + type: 'object', + required: ['repoUrl'], + properties: { + repoUrl: inputProps.repoUrl, + token: inputProps.token, + secrets: inputProps.secrets, + }, + }, + }, + async handler(ctx) { + const { + repoUrl, + secrets, + token: providedToken, + } = ctx.input; + + const octokitOptions = await getOctokitOptions({ + integrations, + credentialsProvider: githubCredentialsProvider, + token: providedToken, + repoUrl: repoUrl, + }); + const client = new Octokit(octokitOptions); + + const {owner, repo} = parseRepoUrl(repoUrl, integrations); + + if (!owner) { + throw new InputError('Invalid repository owner provided in repoUrl'); + } + + const newRepo = await createGithubRepoWithCollaboratorsAndTopics( + client, + repo, + owner, + secrets, + ctx.logger, + ); + + ctx.output('remoteUrl', newRepo.clone_url); + }, + }); +``` + +#### Task context store + +Implement the similar API to CatalogProcessorCache allowing to store markers or keys to enable users to write idempotent actions. +This context persists across retries. + +```typescript +const repoMarker = await cache.get('repo.marker.key'); +``` + +#### Checkpoints + +Checkpoints will allow action authors to create actions where code paths are ignored if already run. This will be provided on a context object and action of author provide a key and a callback. + +```typescript +await ctx.checkpoint('repo.creation', async () => { + const { repoUrl } = await client.rest.Repository.create({}); + return { repoUrl }; +}); +``` + +This checkpoint will be backed with task stored context namespaced with a checkpoint versioned prefix. +It's going look like: + +```json +{ + "v1.task.checkpoint.repo.creation": { + "status": "success", + "result": { + "repoUrl": "https://github.com/backstage/backstage.git" + } + } +} +``` + ## Release Plan -We believe that idempotency is the best way to do it. Idempotency allows to rerun the actions multiple times to gracefully deal with semi-complete actions. - ### Idempotency +We believe that idempotency is the best way to do it. Idempotency allows to rerun the actions multiple times to gracefully deal with semi-complete actions. + ### Serialization of workspace +We believe that a serialization of workspace is a way to achieve re-running the task on a non-sticky way. +That means that the task can be restored and retried on a different scaffolder node. + ### Secrets +Secrets will be stored for a longer period of time in the database and wiped out once the task going into a complete state (successfully finished or archived). + ## Design Details