• Stars
    star
    200
  • Rank 195,325 (Top 4 %)
  • Language
    TypeScript
  • License
    Apache License 2.0
  • Created over 3 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

AWS CDK construct library that can be used to deploy instances of the Construct Hub in any AWS Account.

Construct Hub

This project maintains a AWS Cloud Development Kit construct library that can be used to deploy instances of the Construct Hub in any AWS Account.

This software backs the public instance of the ConstructHub, and can be used to deploy a self-hosted instance with personalized configuration.

Getting Started

⚠️ Disclaimer

The public instance of ConstructHub is Generally Available.

Self-hosted ConstructHub instances are however in active development and should be considered experimental. Breaking changes to the public API of this package are expected to be released without prior notice, and the infrastructure and operational posture of ConstructHub instances may also significantly change.

You are welcome to deploy self-hosted instances of ConstructHub for evaluation purposes, and we welcome any feedback (good or bad) from your experience in doing so.

💰 Cost of running Construct Hub

If you opt to use Construct Hub for processing your CDK packages, you will be subject to charges based on the number of packages processed by Construct Hub. To minimize these charges, you can implement package filters for relevant sources and exclude public NPM packages from the processing list.

Quick Start

Once you have installed the construct-hub library in your project, the simplest way to get started is to create an instance of the ConstructHub construct:

import { App, Stack } from '@aws-cdk/core';
import { ConstructHub } from 'construct-hub';

// The usual... you might have used `cdk init app` instead!
const app = new App();
const stack = new Stack(app, 'StackName', { /* ... */ });

// Now to business!
new ConstructHub(stack, 'ConstructHub');

Personalization

Using a custom domain name

In order to use a custom domain for your ConstructHub instance instead of the default CloudFront domain name, specify the domain property with the following elements:

Attribute Description
zone A Route53 Hosted Zone, where DNS records will be added.
cert An Amazon Certificate Manager certificate, which must be in the us-east-1 region.
monitorCertificateExpiration Set to false if you do not want an alarm to be created when the certificate is close to expiry.

Your self-hosted ConstructHub instance will be served from the root of the provided zone, so the certificate must match this name.

Alternate package sources

By default, ConstructHub has a single package source configured: the public npmjs.com registry. Self-hosted instances typically should list packages from alternate sources, either in addition to packages from npmjs.com, or instead of those.

The packageSources property can be used to replace the default set of package sources configured on the instance. ConstructHub provides IPackageSource implementations for the public npmjs.com registry as well as for private CodeArtifact repositories:

import * as codeartifact from '@aws-cdk/aws-codeartifact';
import { App, Stack } from '@aws-cdk/core';
import { sources, ConstructHub } from 'construct-hub';

// The usual... you might have used `cdk init app` instead!
const app = new App();
const stack = new Stack(app, 'StackName', { /* ... */ });

// Now to business!
const repository = new codeartifact.CfnRepository(stack, 'Repository', {
  // ....
});
new ConstructHub(stack, 'ConstructHub', {
  packageSources: [
    new sources.NpmJs(), // Remove if you do NOT want npmjs.com packages
    new sources.CodeArtifact({ repository }),
  ],
});

You may also implement a custom IPackageSource if you want to index packages from alternate locations. In this case, the component you provide will be responsible for sending notifications to an SQS Queue about newly discovered packages. You may refer to the sources.NpmJs and sources.CodeArtifact implementations as a reference for hos this can be done.

By default, download counts of NPM packages will be fetched periodically from NPM's public API by a Lambda. Since this is not desirable if you are using a private package registry, this is automatically disabled if you specify your own value for packageSources. (But this can be re-enabled through the fetchPackageStats property if needed).

Package deny list

Certain packages may be undesirable to show in your self-hosted ConstructHub instance. In order to prevent a package from ever being listed in construct hub, the denyList property can be configured with a set of DenyListRule objects that specify which package or package versions should never be lested:

import { App, Stack } from '@aws-cdk/core';
import { ConstructHub } from 'construct-hub';

// The usual... you might have used `cdk init app` instead!
const app = new App();
const stack = new Stack(app, 'StackName', { /* ... */ });

// Now to business!
new ConstructHub(stack, 'ConstructHub', {
  denyList: [
    // Denying _all_ versions of the "sneaky-hackery" package
    { packageName: 'sneaky-hackery', reason: 'Mines bitcoins wherever it gets installed' },
    // Denying _a specific_ version of the "bad-release" package
    { packageName: 'bad-release', version: '1.2.3', reason: 'CVE-####-#####' },
  ],
});

Redirecting from additional domains

You can add additional domains that will be redirected to your primary Construct Hub domain:

import * as r53 from '@aws-cdk/aws-route53';

const myDomainZone = r53.HostedZone.fromHostedZoneAttributes(this, 'MyDomainZone', {
  hostedZoneId: 'AZ1234',
  zoneName: 'my.domain.com',
});

new ConstructHub(this, 'ConstructHub', {
  additionalDomains: [ { hostedZone: myDomainZone } ]
});

This will set up full domain redirect using Amazon S3 and Amazon CloudFront. All requests will be redirected to your primary Construct Hub domain.

Decrease deployment footprint

By default, ConstructHub executes the documentation rendering process in the context of isolated subnets. This is a defense-in-depth mechanism to mitigate the risks associated with downloading aribtrary (un-trusted) npm packages and their dependency closures.

This layer of security implies the creation of a number of resources that can increase the operating cost of your self-hosted instance: several VPC endpoints are created, an internal CodeArtifact repository needs to be provisioned, etc...

While we generally recommend leaving these features enabled, if your self-hosted ConstructHub instance only indexes trusted packages (as could be the case for an instance that does not list packages from the public npmjs.com registry), you may set the isolateLambdas setting to false.

⚙️ Operating a self-hosted instance

  1. Application Overview provides a high-level description of the components that make a ConstructHub instance. This is a great starting point for people who consider operating a self-hosted instance of ConstructHub; and for new operators on-boarding the platform.

  2. Operator Runbook is a series of diagnostics and troubleshooting guides indended for operators to have a quick and easy way to navigate a ConstructHub instance when they are reacting to an alarm or bug report.

🐤 Deployment Canaries

Construct Hub provides several built-in validation mechanisms to make sure the deployment of your instance is continuously operating as expected.

These mechanisms come in the form of canary testers that are part of the ConstructHub deployment stack. Each canary runs periodically and performs a different check, triggering a different CloudWatch alarm in case it detects a failure.

We recommend that you use staged deployments, and block promotions to the production stage in case any preivous stage triggers an alarm within a specific timeframe.

Discovery Canary

When configuring an NpmJs package source, a package discovery canary can be enabled using the enableCanary property (and optionally configured using the canaryPackage and canarySla properties). This feature is activated by default and monitors availability of releases of the construct-hub-probe npm package in the ConstructHub instance.

Probe packages, such as construct-hub-probe are published frequently (e.g: every 3 hours or more frequently), and can be used to ensure the ConstructHub instance correctly discovers, indexes and represents those packages.

If a different package or SLA should be used, you can configure the NpmJs package source manually like so:

import * as codeartifact from '@aws-cdk/aws-codeartifact';
import { App, Stack } from '@aws-cdk/core';
import { sources, ConstructHub } from 'construct-hub';

const app = new App();
const stack = new Stack(app, 'StackName', { /* ... */ });

new ConstructHub(stack, 'ConstructHub', {
  // ...
  packageSources: [
    // ...
    new sources.NpmJs({
      enableCanary: true, // This is the default
      canaryPackage: '@acme/my-constructhub-probe',
      canarySla: Duration.minutes(30),
    }),
    // ...
  ],
  // ...
});

In case the new package isn't fully available in the predefined SLA, a high severity CloudWatch alarm will trigger, which will in turn trigger the configured action for low severity alarms.

See Monitoring & Alarms

The operator runbook contains instructions on how to diagnose and mitigate the root cause of the failure.

💅 Customizing the frontend

There are a number of customizations available in order to make your private construct hub better tailored to your organization.

Package Tags

Configuring package tags allows you to compute additional labels to be applied to packages. These can be used to indicate to users which packages are owned by trusted organizations, or any other arbitrary conditions, and can be referenced while searching.

For example:

new ConstructHub(this, "ConstructHub", {
  ...myProps,
  packageTags: [{
    id: 'official',
    condition: TagCondition.field('name').eq('construct-hub'),
    keyword: {
      label: 'Official',
      color: '#00FF00',
    },
    highlight: {
      label: 'Vended by AWS',
      color: '#00FF00',
    }
  }]
});

The above example will result in packages with the name of construct-hub to receive the Official tag, which is colored green and displayed amongst the list of keywords. Additionally the highlight key shows this as a highlighted item on the package's card.

The searchFilter key can also be used to show tags as search filters grouped together.

const authorsGroup = new PackageTagGroup("authors", {
  label: "Authors",
  tooltip: "Information about the authors filter",
  filterType: FilterType.checkbox(),
});

const isAws = TagCondition.field('name').eq('construct-hub');
new ConstructHub(this, "ConstructHub", {
  ...myProps,
  packageTags: [{
    id: 'AWS',
    condition: isAws,
    searchFilter: {
      group: authorsGroup,
      display: 'AWS',
    },
  }, {
    id: 'Community',
    condition: TagCondition.not(isAws),
    searchFilter: {
      group: authorsGroup,
      display: 'AWS',
    },
  }]
});

The above will show a list of Authors filters on the search results page with a checkbox for each AWS and Community packages, allowing users to filter results by the presence of these tags.

Combinations of conditions are also supported:

new ConstructHub(this, "ConstructHub", {
  ...myProps,
  packageTags: [{
    label: 'Official',
    color: '#00FF00',
    condition: TagCondition.or(
      TagCondition.field('name').eq('construct-hub'),
      TagCondition.field('name').eq('construct-hub-webapp'),
    ),
  }]
});

// or more succintly if you have a long list
condition: TagCondition.or(
  ...['construct-hub', 'construct-hub-webapp', '...',]
    .map(name => TagCondition.field('name').eq(name))
),

You can assert against any value within package json including nested ones.

TagCondition.field('constructHub', 'nested', 'key').eq('value');

// checks
packageJson?.constructHub?.nested?.key === value;

You can also assert that a string occurs at least a certain number of times within the package's README.

TagCondition.readme().includes('ECS');
TagCondition.readme().includes('fargate', { atLeast: 3, caseSensitive: false });

Package Links

Configuring package links allows you to replace the Repository, License, and Registry links on the package details page with whatever you choose.

For example:

new ConstructHub(this, "ConstructHub", {
  ...myProps,
  packageLinks: [{
    linkLabel: 'Service Level Agreement',
    configKey: 'SLA',
  }, {
    linkLabel: 'Contact',
    configKey: 'Contact',
    linkText: 'Email Me!',
    allowedDomains: ['me.com'],
  }]
});

This would allow publishers to add the following to their package.json:

"constructHub": {
  "packageLinks": {
    "SLA": "https://support.mypackage.com",
    "Contact": "me.com/contact"
  }
}

Then the links on the corresponding package page would show these items as configured.

RSS/ATOM feeds for recent packages

Construct hub automatically generates RSS/ATOM feed showing the list of latest 100 packages added. The generated feed can be configured to get release notes from GitHub by configuring it with personal access token. The access token has to be stored in AWS Secretsmanager and should be passed to feedConfiguration

For example:

new ConstructHub(this, "ConstructHub", {
  ...myProps,
  feedConfiguration: {
      gitHubTokenSecret: secretsManager.Secret.fromSecretCompleteArn(this, 'GitHubToken', '<arn:aws:secretsmanager:us-east-2:11111111111:secret:releaseNotesFetcherGitHubToken-abCd1>'),
      feedDescription: 'Latest Constructs in the construct hub',
      feedTitle: 'Latest constructs',
    }
  }
});

Home Page

The home page is divided into sections, each with a header and list of packages. Currently, for a given section you can display either the most recently updated packages, or a curated list of packages.

For example:

new ConstructHub(this, "ConstructHub", {
  ...myProps,
  featuredPackages: {
    sections: [
      {
        name: "Recently updated",
        showLastUpdated: 4
      },
      {
        name: "From the AWS CDK",
        showPackages: [
          {
            name: "@aws-cdk/core"
          },
          {
            name: "@aws-cdk/aws-s3",
            comment: "One of the most popular AWS CDK libraries!"
          },
          {
            name: "@aws-cdk/aws-lambda"
          },
          {
            name: "@aws-cdk/pipelines"
            comment: "The pipelines L3 construct library abstracts away many of the details of managing software deployment within AWS."
          }
        ]
      }
    ]
  }
});

Browse Categories

The Construct Hub home page includes a section that displays a set of buttons that represent browsing categories (e.g. "Databases", "Monitoring", "Serverless", etc).

You can use the categories option to configure these categories. Each category is defined by a title and a url, which will be the link associated with the button.

new ConstructHub(this, "ConstructHub", {
  ...myProps,
  categories: [
    { title: 'Databases', url: '?keywords=databases' },
    { title: 'Monitoring', url: '?q=monitoring' },
    { title: 'Partners', url: '?tags=aws-partner' }
  ]
});

Feature Flags

Feature flags for the web app can be used to enable or disable experimental features. These can be customized through the featureFlags property - for more information about the available flags, check the documentation for https://github.com/cdklabs/construct-hub-webapp/.

AppRegistry

By default, an AppRegistry application will be created that is associated with the stack you put the ConstructHub construct in.

Contributing

If you are looking to contribute to this project, but don't know where to start, have a look at our contributing guide!

👮 Security

See CONTRIBUTING for more information.

⚖️ License

This project is licensed under the Apache-2.0 License.

More Repositories

1

cdk-nag

Check CDK applications for best practices using a combination of available rule packs
TypeScript
782
star
2

cdk-watchful

Watching what's up with your CDK apps since 2019
TypeScript
531
star
3

cdk-monitoring-constructs

Easy-to-use CDK constructs for monitoring your AWS infrastructure
TypeScript
456
star
4

aws-delivlib

setup and manage continuous delivery pipelines for code libraries in multiple languages
TypeScript
372
star
5

cdk-pipelines-github

TypeScript
321
star
6

cdk-ecr-deployment

A CDK construct to deploy docker image to Amazon ECR
Go
152
star
7

cdk-dynamo-table-viewer

A CDK construct which exposes an endpoint with the contents of a DynamoDB table
TypeScript
124
star
8

cdk-stacksets

TypeScript
80
star
9

cdk-docker-image-deployment

TypeScript
75
star
10

cdk-triggers

TypeScript
73
star
11

cdk-validator-cfnguard

TypeScript
67
star
12

cdk-cloudformation

TypeScript
60
star
13

decdk

Define AWS CDK applications declaratively
TypeScript
60
star
14

cdk-ecs-service-extensions

TypeScript
59
star
15

cdk-from-cfn

A cloudformation json -> cdk typescript transpiler.
Rust
58
star
16

cdk-import

Generates CDK level 1 constructs for public CloudFormation Registry types and modules
TypeScript
52
star
17

cdk-app-cli

The operator CLI for CDK apps.
TypeScript
52
star
18

publib

A unified toolchain for publishing libraries to popular package managers (formally jsii-release)
TypeScript
52
star
19

cdk-drift-monitor

Monitors for CloudFormation stack drifts.
TypeScript
48
star
20

jsii-docgen

Generates reference documentation for jsii modules
TypeScript
48
star
21

aws-cdk-testing-examples

Java
39
star
22

cdk-ecs-codedeploy

TypeScript
34
star
23

cdk-enterprise-iac

Utilities for using CDK within enterprise constraints
TypeScript
33
star
24

cdk-tweet-queue

SQS queue fed with a stream of tweets from a Twitter search
TypeScript
29
star
25

cdk-ssm-documents

TypeScript
27
star
26

awscdk-service-spec

TypeScript
25
star
27

awscdk-appsync-utils

TypeScript
24
star
28

aws-secrets-github-sync

Sync GitHub repository secrets from AWS Secrets Manager
TypeScript
22
star
29

cdk-amazon-chime-resources

TypeScript
22
star
30

construct-hub-webapp

React web app for Construct Hub
TypeScript
21
star
31

json2jsii

Generates jsii-compatible structs from JSON schemas
TypeScript
20
star
32

node-sscaff

Stupid scaffolding: copies an entire directory with variable substitution
TypeScript
20
star
33

cdk-cicd-wrapper

This repository contains the infrastructure as code to wrap your AWS CDK project with CI/CD around it.
TypeScript
20
star
34

jsii-srcmak

Generate multi-language object-oriented source code from typescript
TypeScript
19
star
35

awscdk-v1-stack-finder

TypeScript
18
star
36

awscdk-asset-kubectl

TypeScript
18
star
37

cdk-skylight

CDK Skylight is a set of Level 3 constructs for the Microsoft products on AWS
TypeScript
17
star
38

markmac

Embed program outputs in markdown
TypeScript
17
star
39

cdk-verified-permissions

Amazon Verified Permissions L2 CDK Constructs
TypeScript
16
star
40

awscdk-change-analyzer

A toolkit that analyzes the differences between two cloud infrastructures states.
HTML
13
star
41

cdk-ethereum-node

CDK construct to deploy an Ethereum node running on Amazon Managed Blockchain
TypeScript
11
star
42

aws-lambda-rust

TypeScript
10
star
43

cdk-appflow

This repository contains L2 AWS CDK constructs for Amazon AppFlow
TypeScript
9
star
44

aws-cdk-notices

Static website for the distribution of notices to AWS CDK users.
TypeScript
8
star
45

cdk-hyperledger-fabric-network

CDK construct to deploy a Hyperledger Fabric network running on Amazon Managed Blockchain
TypeScript
7
star
46

cfn-resources

TypeScript
7
star
47

cdk-nag-go

cdk-nag bindings for Go.
Go
7
star
48

awscdk-asset-awscli

TypeScript
7
star
49

cdk-codepipeline-extensions

Go
7
star
50

cdk-aws-sagemaker-role-manager

Create roles and policies for ML Activities and ML Personas
TypeScript
6
star
51

cdklabs-projen-project-types

TypeScript
6
star
52

cdk-golden-signals-dashboard

TypeScript
6
star
53

awscdk-lambda-dotnet

TypeScript
5
star
54

cdk-deployer

A CDK construct library for deploying artifacts via CodeDeploy.
TypeScript
4
star
55

awscdk-dynamodb-global-tables

TypeScript
4
star
56

node-backpack

TypeScript
3
star
57

cfunctions

TypeScript
3
star
58

cdk-dynamo-table-viewer-go

A CDK construct which exposes an endpoint with the contents of a DynamoDB table Topics Resources License
Go
3
star
59

cdk-cdk8s-reinvent-2021

Java
2
star
60

construct-hub-probe

Probe package intended to test construct hub instances
TypeScript
2
star
61

construct-hub-cli

TypeScript
1
star
62

cdk-assets

TypeScript
1
star
63

cloud-assembly-schema

TypeScript
1
star
64

cdk-ecs-codedeploy-go

Go
1
star
65

cdk-generate-synthetic-examples

Find all classes in the JSII assembly that don't yet have any example code associated with them, and generate a synthetic example that shows how to instantiate the type.
TypeScript
1
star
66

cdk-ecs-service-extensions-go

Go
1
star
67

cdk-aws-sagemaker-role-manager-go

Go
1
star