Ryan Wilson
68684df471
Jenkins shared library and CDK constructs for AWS infrastructure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
498 lines
9.6 KiB
Markdown
498 lines
9.6 KiB
Markdown
# Jenkins Utilities Reference
|
|
|
|
All available utility functions in the `spicy-automation` Jenkins shared library.
|
|
|
|
## Table of Contents
|
|
|
|
- [cdkUtils](#cdkutils) - CDK command execution
|
|
- [dockerUtils](#dockerutils) - Docker/Nexus operations
|
|
- [gitUtils](#gitutils) - Git information
|
|
- [giteaUtils](#giteautils) - Gitea commit status
|
|
- [awsUtils](#awsutils) - AWS CLI operations
|
|
- [spicyUtils](#spicyutils) - Pipeline utilities
|
|
- [accounts](#accounts) - Account configurations
|
|
- [manualApproval](#manualapproval) - Approval gates
|
|
|
|
---
|
|
|
|
## cdkUtils
|
|
|
|
Execute AWS CDK commands from Jenkins pipelines.
|
|
|
|
### `cdkUtils.deploy(Map args)`
|
|
|
|
Deploy a CDK stack.
|
|
|
|
```groovy
|
|
cdkUtils.deploy(
|
|
account: [
|
|
region: "ca-central-1",
|
|
jenkinsAwsCredentialsId: "aws-credentials",
|
|
accountId: "123456789012" // optional
|
|
],
|
|
stackName: "my-stack",
|
|
stackType: "vpc", // vpc, ecs-cluster, ecs-service
|
|
context: [ // Additional CDK context
|
|
ownerTag: "MyTeam",
|
|
productTag: "myapp"
|
|
],
|
|
workDir: "." // optional, defaults to current dir
|
|
)
|
|
```
|
|
|
|
### `cdkUtils.diff(Map args)`
|
|
|
|
Show changes between deployed and local stack.
|
|
|
|
```groovy
|
|
cdkUtils.diff(
|
|
account: account,
|
|
stackName: "my-stack",
|
|
stackType: "vpc",
|
|
context: context
|
|
)
|
|
```
|
|
|
|
### `cdkUtils.synth(Map args)`
|
|
|
|
Synthesize CloudFormation template.
|
|
|
|
```groovy
|
|
cdkUtils.synth(
|
|
account: account,
|
|
stackName: "my-stack",
|
|
stackType: "vpc",
|
|
context: context
|
|
)
|
|
```
|
|
|
|
### `cdkUtils.destroy(Map args)`
|
|
|
|
Destroy a CDK stack.
|
|
|
|
```groovy
|
|
cdkUtils.destroy(
|
|
account: account,
|
|
stackName: "my-stack",
|
|
stackType: "vpc",
|
|
context: context
|
|
)
|
|
```
|
|
|
|
### `cdkUtils.install(Map args)`
|
|
|
|
Install CDK dependencies.
|
|
|
|
```groovy
|
|
cdkUtils.install(workDir: ".")
|
|
```
|
|
|
|
### `cdkUtils.build(Map args)`
|
|
|
|
Build CDK TypeScript (optional - ts-node runs directly).
|
|
|
|
```groovy
|
|
cdkUtils.build(workDir: ".")
|
|
```
|
|
|
|
### `cdkUtils.test(Map args)`
|
|
|
|
Run CDK tests.
|
|
|
|
```groovy
|
|
cdkUtils.test(workDir: ".")
|
|
```
|
|
|
|
---
|
|
|
|
## dockerUtils
|
|
|
|
Docker operations with Nexus registry support.
|
|
|
|
**Default Configuration:**
|
|
|
|
- Registry: `nexus.kodeniks.com`
|
|
- Repository: `docker-hosted`
|
|
- Credentials: `kodeniks-nexus-repository`
|
|
|
|
### `dockerUtils.buildAndPush(Map args)`
|
|
|
|
Build and push a Docker image to Nexus.
|
|
|
|
```groovy
|
|
def imageRef = dockerUtils.buildAndPush(
|
|
imageName: "my-service", // required
|
|
dockerfile: "Dockerfile", // default: Dockerfile
|
|
context: ".", // default: .
|
|
buildArgs: [ // optional
|
|
NODE_ENV: "production",
|
|
VERSION: "1.0.0"
|
|
],
|
|
tagLatest: true, // default: true on main branch
|
|
compareWithLatest: true, // default: true, skip if unchanged
|
|
registry: "nexus.kodeniks.com", // optional override
|
|
repository: "docker-hosted", // optional override
|
|
credentialsId: "kodeniks-nexus-repository" // optional override
|
|
)
|
|
|
|
echo "Pushed: ${imageRef}"
|
|
// Output: nexus.kodeniks.com/docker-hosted/my-service:abc1234
|
|
```
|
|
|
|
### `dockerUtils.buildImage(Map args)`
|
|
|
|
Build a Docker image without pushing.
|
|
|
|
```groovy
|
|
def containerName = dockerUtils.buildImage(
|
|
imageName: "my-service",
|
|
dockerfile: "Dockerfile",
|
|
context: ".",
|
|
buildArgs: [NODE_ENV: "production"]
|
|
)
|
|
```
|
|
|
|
### `dockerUtils.tagImage(Map args)`
|
|
|
|
Tag an image for Nexus registry.
|
|
|
|
```groovy
|
|
dockerUtils.tagImage(
|
|
imageName: "my-service",
|
|
tagLatest: true // also tag as 'latest'
|
|
)
|
|
```
|
|
|
|
### `dockerUtils.pushImage(Map args)`
|
|
|
|
Push image to Nexus with smart comparison.
|
|
|
|
```groovy
|
|
def pushed = dockerUtils.pushImage(
|
|
imageName: "my-service",
|
|
tagLatest: true,
|
|
compareWithLatest: true // skip if identical to remote latest
|
|
)
|
|
|
|
if (pushed) {
|
|
echo "Image was pushed"
|
|
} else {
|
|
echo "Image unchanged, push skipped"
|
|
}
|
|
```
|
|
|
|
### `dockerUtils.pullImage(Map args)`
|
|
|
|
Pull an image from Nexus.
|
|
|
|
```groovy
|
|
def imageRef = dockerUtils.pullImage(
|
|
imageName: "my-service",
|
|
tag: "latest" // default: latest
|
|
)
|
|
```
|
|
|
|
### `dockerUtils.login(Map args)`
|
|
|
|
Login to Nexus registry.
|
|
|
|
```groovy
|
|
dockerUtils.login()
|
|
// Or with custom registry:
|
|
dockerUtils.login(registry: "other-nexus.example.com")
|
|
```
|
|
|
|
### `dockerUtils.prune()`
|
|
|
|
Clean up dangling Docker images.
|
|
|
|
```groovy
|
|
dockerUtils.prune()
|
|
```
|
|
|
|
### `dockerUtils.copyFromImage(Map args)`
|
|
|
|
Copy files from a Docker image.
|
|
|
|
```groovy
|
|
dockerUtils.copyFromImage(
|
|
imageID: "my-image:latest",
|
|
dockerPath: "/app/dist",
|
|
jenkinsPath: "./dist"
|
|
)
|
|
```
|
|
|
|
### `dockerUtils.getImageRefSHA(Map args)`
|
|
|
|
Get full image reference with SHA tag.
|
|
|
|
```groovy
|
|
def ref = dockerUtils.getImageRefSHA(imageName: "my-service")
|
|
// Returns: nexus.kodeniks.com/docker-hosted/my-service:abc1234
|
|
```
|
|
|
|
### `dockerUtils.getImageRefLatest(Map args)`
|
|
|
|
Get full image reference with latest tag.
|
|
|
|
```groovy
|
|
def ref = dockerUtils.getImageRefLatest(imageName: "my-service")
|
|
// Returns: nexus.kodeniks.com/docker-hosted/my-service:latest
|
|
```
|
|
|
|
---
|
|
|
|
## gitUtils
|
|
|
|
Git repository information.
|
|
|
|
### `gitUtils.getSHA()`
|
|
|
|
Get full commit SHA.
|
|
|
|
```groovy
|
|
def sha = gitUtils.getSHA()
|
|
// Returns: abc123def456...
|
|
```
|
|
|
|
### `gitUtils.getShortSHA()`
|
|
|
|
Get short commit SHA (7 characters).
|
|
|
|
```groovy
|
|
def shortSha = gitUtils.getShortSHA()
|
|
// Returns: abc123d
|
|
```
|
|
|
|
### `gitUtils.getBranch()`
|
|
|
|
Get current branch name.
|
|
|
|
```groovy
|
|
def branch = gitUtils.getBranch()
|
|
// Returns: main, feature/xyz, etc.
|
|
```
|
|
|
|
### `gitUtils.isMain()`
|
|
|
|
Check if on main branch.
|
|
|
|
```groovy
|
|
if (gitUtils.isMain()) {
|
|
echo "On main branch - deploying!"
|
|
}
|
|
```
|
|
|
|
### `gitUtils.getRemoteURL()`
|
|
|
|
Get Git remote URL.
|
|
|
|
```groovy
|
|
def url = gitUtils.getRemoteURL()
|
|
// Returns: git@git.kodeniks.com:CORP/my-repo.git
|
|
```
|
|
|
|
---
|
|
|
|
## giteaUtils
|
|
|
|
Update Gitea commit status.
|
|
|
|
**Default Configuration:**
|
|
|
|
- Gitea URL: `https://git.kodeniks.com`
|
|
- Credentials: `kodeniks-gitea-token`
|
|
|
|
### `giteaUtils.setSuccess(context)`
|
|
|
|
Set commit status to success.
|
|
|
|
```groovy
|
|
giteaUtils.setSuccess("build")
|
|
giteaUtils.setSuccess("deploy")
|
|
```
|
|
|
|
### `giteaUtils.setPending(context)`
|
|
|
|
Set commit status to pending.
|
|
|
|
```groovy
|
|
giteaUtils.setPending("build")
|
|
```
|
|
|
|
### `giteaUtils.setFailed(context)`
|
|
|
|
Set commit status to failed.
|
|
|
|
```groovy
|
|
giteaUtils.setFailed("build")
|
|
```
|
|
|
|
### `giteaUtils.setError(context)`
|
|
|
|
Set commit status to error.
|
|
|
|
```groovy
|
|
giteaUtils.setError("build")
|
|
```
|
|
|
|
### `giteaUtils.updateStatus(Map args)`
|
|
|
|
Update commit status with full control.
|
|
|
|
```groovy
|
|
giteaUtils.updateStatus(
|
|
context: "build",
|
|
state: "success", // success, pending, failure, error
|
|
message: "Build passed",
|
|
giteaUrl: "https://git.kodeniks.com", // optional override
|
|
credentialsId: "kodeniks-gitea-token" // optional override
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## awsUtils
|
|
|
|
AWS CLI operations.
|
|
|
|
### `awsUtils.assumeRole(Map args)`
|
|
|
|
Assume an IAM role.
|
|
|
|
```groovy
|
|
awsUtils.assumeRole(
|
|
roleArn: "arn:aws:iam::123456789012:role/MyRole",
|
|
sessionName: "jenkins-deploy"
|
|
)
|
|
```
|
|
|
|
### `awsUtils.getCallerIdentity(Map args)`
|
|
|
|
Get current AWS identity.
|
|
|
|
```groovy
|
|
def identity = awsUtils.getCallerIdentity(
|
|
jenkinsAwsCredentialsId: "aws-credentials",
|
|
region: "ca-central-1"
|
|
)
|
|
```
|
|
|
|
### `awsUtils.describeStacks(Map args)`
|
|
|
|
Describe CloudFormation stacks.
|
|
|
|
```groovy
|
|
def stacks = awsUtils.describeStacks(
|
|
jenkinsAwsCredentialsId: "aws-credentials",
|
|
region: "ca-central-1",
|
|
stackName: "my-stack"
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## spicyUtils
|
|
|
|
Pipeline utility functions.
|
|
|
|
### `spicyUtils.stageWithFailure(name, closure)`
|
|
|
|
Run a stage that sets Gitea status on failure.
|
|
|
|
```groovy
|
|
spicyUtils.stageWithFailure("Build") {
|
|
sh "npm run build"
|
|
}
|
|
```
|
|
|
|
### `spicyUtils.withRetry(Map args, closure)`
|
|
|
|
Retry a block with exponential backoff.
|
|
|
|
```groovy
|
|
spicyUtils.withRetry(maxAttempts: 3, delay: 5) {
|
|
sh "flaky-command"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## accounts
|
|
|
|
Multi-account configuration management.
|
|
|
|
### `accounts.get()`
|
|
|
|
Get all account configurations.
|
|
|
|
```groovy
|
|
def allAccounts = accounts.get()
|
|
|
|
def prodAccount = allAccounts.SPICY_CA_CENRAL_1_PROD
|
|
def devAccount = allAccounts.SPICY_CA_CENRAL_1_DEV
|
|
```
|
|
|
|
### Account Object Properties
|
|
|
|
| Property | Description |
|
|
| ------------------------- | ------------------------------ |
|
|
| `accountId` | AWS Account ID |
|
|
| `region` | AWS Region |
|
|
| `jenkinsAwsCredentialsId` | Jenkins credential ID |
|
|
| `vpcStackName` | Default VPC stack name |
|
|
| `ecsClusterStackName` | Default ECS cluster stack name |
|
|
|
|
### Available Accounts
|
|
|
|
| Key | Description |
|
|
| --------------------------- | ----------------------- |
|
|
| `SPICY_CA_CENRAL_1` | Base account |
|
|
| `SPICY_CA_CENRAL_1_DEV` | Development environment |
|
|
| `SPICY_CA_CENRAL_1_SANDBOX` | Sandbox environment |
|
|
| `SPICY_CA_CENRAL_1_QA` | QA environment |
|
|
| `SPICY_CA_CENRAL_1_STAGING` | Staging environment |
|
|
| `SPICY_CA_CENRAL_1_PROD` | Production environment |
|
|
|
|
---
|
|
|
|
## manualApproval
|
|
|
|
Manual approval gates for pipelines.
|
|
|
|
### `manualApproval(Map args)`
|
|
|
|
Request manual approval before proceeding.
|
|
|
|
```groovy
|
|
manualApproval(
|
|
message: "Deploy to production?",
|
|
submitter: "admin,deployers", // optional: allowed approvers
|
|
timeout: 24, // optional: hours to wait
|
|
timeoutUnit: "HOURS" // optional: HOURS, MINUTES, DAYS
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## spicyDefaults
|
|
|
|
Apply default pipeline configuration.
|
|
|
|
### `spicyDefaults(Map args)`
|
|
|
|
Merge defaults into pipeline arguments.
|
|
|
|
```groovy
|
|
def call(Map args) {
|
|
args = spicyDefaults(args)
|
|
// args now has default pipelineProperties, etc.
|
|
}
|
|
```
|
|
|
|
Default properties applied:
|
|
|
|
- Build discarder (keep 10 builds)
|
|
- Disable concurrent builds
|
|
- GitHub project URL (if applicable)
|