Helm chart for imgproxy

This repo contains a Helm chart to deploy imgproxy.

imgproxy is a fast and secure standalone server for resizing and converting remote images. The main principles of imgproxy are simplicity, speed, and security.

TL;DR

To install imgproxy to your kubernetes cluster simply run:

helm repo add imgproxy https://helm.imgproxy.net/

# With Helm 3
helm upgrade -i imgproxy imgproxy/imgproxy

# With Helm 2
helm upgrade -i --name imgproxy imgproxy/imgproxy

Introduction

imgproxy can be used to provide a fast and secure way to replace all the image resizing code of your web application (like calling ImageMagick or GraphicsMagick, or using libraries), while also being able to resize everything on the fly, fast and easy. imgproxy is also indispensable when handling lots of image resizing, especially when images come from a remote source.

imgproxy does one thing — resizing remote images — and does it well. It works great when you need to resize multiple images on the fly to make them match your application design without preparing a ton of cached resized images or re-doing it every time the design changes.

imgproxy is a Go application, ready to be installed and used in any Unix environment — also ready to be containerized using Docker.

See this article for a good intro and all the juicy details! imgproxy: Resize your images instantly and securely

See official README for more.

Prerequisites

• Kubernetes 1.4+ with Beta APIs enabled

Installing chart

helm repo add imgproxy https://helm.imgproxy.net/

# With Helm 3
helm upgrade -i imgproxy imgproxy/imgproxy

# With Helm 2
helm upgrade -i --name imgproxy imgproxy/imgproxy

The command deploys imgproxy on the Kubernetes cluster in the default configuration. The configuration section lists various ways to override default configuration during deployment.

Tip: To list all releases use helm list

Uninstalling the Chart

helm delete imgproxy

The command removes all the Kubernetes components associated with the chart and deletes the release.

Configuration

Specify each parameter using the --set key=value[,key=value] argument to helm install or provide your own file via -f values.yaml. For example,

helm upgrade -i imgproxy \
  --namespace imgproxy \
  --set image.tag=v2.10.0 \
  imgproxy/imgproxy

The above command installs a specified version of imgproxy.

Supported Chart values

URL Signature Settings

Value	Description	Default
features.urlSignature.enabled	enable URL encoding	true
features.urlSignature.key	hex-encoded key for URL encoding	CHANGE IT!!!
features.urlSignature.salt	hex-encoded salt for URL encoding	CHANGE IT!!!
features.urlSignature.signatureSize	number of bytes to use for signature before encoding to Base64	32

Imgproxy Server Settings

Value	Description	Default
features.server.readTimeout	the maximum duration (in seconds) for reading the entire image request, including the body	10
features.server.writeTimeout	the maximum duration (in seconds) for writing the response	10
features.server.keepAliveTimeout	the maximum duration (in seconds) to wait for the next request before closing the connection. When set to 0, keep-alive is disabled	10
features.server.downloadTimeout	the maximum duration (in seconds) for downloading the source image	5
features.server.concurrency	the maximum number of image requests to be processed simultaneously	double number of CPU cores
features.server.maxClients	the maximum number of simultaneous active connections	concurrency * 10
features.server.ttl	duration in seconds sent in Expires and Cache-Control: max-age headers	3600
features.server.setCanonicalHeader	when true and the source image has http or https scheme, set rel="canonical" HTTP header to the value of the source image URL.	false
features.server.cacheControlPassthrough	when true and source image response contains Expires or Cache-Control headers, reuse those header	false
features.server.soReuseport	when true, enables SO_REUSEPORT socket option (currently on linux and darwin only)	false
features.server.pathPrefix	URL path prefix.
features.server.userAgent	User-Agent header that will be sent with source image request	imgproxy/%current_version
features.server.useEtag	when true, enables using ETag header for the cache control	false
features.server.etagBuster	Change this to change ETags for all the images
features.server.customRequestHeaders	PRO: list of custom headers that imgproxy will send while requesting the source image, divided by \; (can be redefined by IMGPROXY_CUSTOM_HEADERS_SEPARATOR)
features.server.customResponseHeaders	PRO: list of custom response headers, divided by ; (can be redefined by IMGPROXY_CUSTOM_HEADERS_SEPARATOR)
features.server.customHeadersSeparator	PRO: string that will be used as a custom headers separator	\;
features.server.enableDebugHeaders	when true, imgproxy will add X-Origin-Content-Length header with the value is size of the source image.	false
features.server.name	PRO: The Server header value.	imgproxy

Imgproxy Security Settings

Value	Description	Default
features.security.secret	the authorization token. If specified, request should contain the Authorization: Bearer %secret% header
features.security.maxSrcResolution	the maximum resolution of the source image, in megapixels.	16.8
features.security.maxSrcFileSize	the maximum size of the source image, in bytes.	0 (disabled)
features.security.maxAnimationFrames	the maximum of animated image frames to being processed.	1
features.security.maxSvgCheckBytes	the maximum number of bytes imgproxy will read to recognize SVG.	32KB
features.security.allowOrigin	when set, enables CORS headers with provided origin. CORS headers are disabled by default.	false
features.security.allowedSources	whitelist of source image URLs prefixes divided by comma. When blank, imgproxy allows all source image URLs.
features.security.ignoreSslVerification	When true, disables SSL verification	false
features.security.developmentErrorsMode	when true, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack trace	false

Image Compression Settings

Value	Description	Default
features.compression.quality	quality of the resulting image, percentage	80
features.compression.formatQuality	default quality of the resulting image per format, comma divided.
features.compression.gzipCompression	GZip compression level	5
features.compression.jpegProgressive	when true, enables progressive compression of JPEG	false
features.compression.jpegNoSubsample	PRO: when true, chrominance subsampling is disabled. This will improve quality at the cost of larger file size	false
features.compression.jpegTrellisQuant	PRO: when true, enables trellis quantisation for each 8x8 block. Reduces file size but increases compression time	false
features.compression.jpegOvershootDeringing	PRO: when true, enables overshooting of samples with extreme values.
features.compression.jpegOptimizeScans	PRO: when true, split the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time. Requires IMGPROXY_JPEG_PROGRESSIVE to be true	false
features.compression.jpegQuantTable	quantization table to use. Supported values are: 0-8	0
features.compression.pngInterlaced	when true, enables interlaced compression of PNG	false
features.compression.pngQuantize	when true, enables PNG quantization. libvips should be built with libimagequant support	false
features.compression.pngQuantizationColors	maximum number of quantization palette entries. Should be between 2 and 256	256
features.compression.gifOptimizeFrames	PRO: when true, enables GIF frames optimization; this may produce a smaller result, but may increase compression time	false
features.compression.gifOptimizeTransparency	PRO: when true, enables GIF transparency optimization; this may produce a smaller result, but may increase compression time	false
features.compression.avifSpeed	controls the CPU effort spent improving compression (0-8).	5

Detection of WEBP/Avif Support by Browsers

Value	Description	Default
features.formatsSupportDetection.webp.enabled	Enables WebP support detection. When the file extension is omitted in the imgproxy URL and browser supports WebP, imgproxy will use it as the resulting format	false
features.formatsSupportDetection.webp.enforced	Enables WebP support detection and enforces WebP usage. If the browser supports WebP, it will be used as resulting format even if another extension is specified in the imgproxy URL	false
features.formatsSupportDetection.avif.enabled	Enables AVIF support detection.	false
features.formatsSupportDetection.avif.enforced	Enables AVIF support detection and enforces AVIF usage	false

Imgproxy Client Hints

Value	Description	Default
features.clientHintsSupport.enabled	Enables Client Hints support when the width is ommited for automatic responsive images	false

Video Thumbnails

Value	Description	Default
features.videoThumbnails.enabled	PRO: when true, enables video thumbnails generation	false
features.videoThumbnails.probeSize	PRO: the maximum amount of bytes used to determine the format. Lower values can decrease memory usage but can produce inaccurate data or even lead to errors	5000000
features.videoThumbnails.maxAnalyzeDuration	PRO: the maximum of milliseconds used to get the stream info. Low values can decrease memory usage but can produce inaccurate data or even lead to errors. When set to 0, the heuristic is used	0
features.videoThumbnails.second	PRO: the timestamp of the frame in seconds that will be used for a thumbnail	1

Watermark

Value	Description	Default
features.watermark.data	Base64-encoded image data
features.watermark.path	Path to the locally stored image
features.watermark.url	Watermark image URL
features.watermark.opacity	Watermark base opacity
features.watermark.cacheSize	PRO: size of custom watermarks cache. When set to 0, watermarks cache is disabled. By default 256 watermarks are cached	256

Unsharpening

Value	Description	Default
features.unsharpening.mode	PRO: controls when unsharpenning mask should be applied (auto, none, always).	auto
features.unsharpening.weight	PRO: a floating-point number that defines how neighbor pixels will affect the current pixel.	1
features.unsharpening.dividor	PRO: a floating-point number that defines the unsharpening strength.	24

Fallback Image

Value	Description	Default
features.fallbackImage.data	Base64-encoded image data. You can easily calculate it with `base64 tmp/fallback.png	tr -d '\n'`
features.fallbackImage.url	fallback image URL.
features.fallbackImage.httpCode	HTTP code for the fallback image response.	200
features.fallbackImage.ttl	A duration (in seconds) sent via the Expires and Cache-Control:max-age HTTP headers when a fallback image was used.When blank or 0, the value from IMGPROXY_TTL is used.

Skip Processing by imgproxy

Value	Description	Default
features.skipProcessing.formats	list of formats that imgproxy shouldn't process, comma-divided.

Presets

Value	Description	Default
features.presets.definitions	set of preset definitions, comma-divided
features.presets.onlyPresets	disable all URL formats and enable presets-only mode	false

AWS support

Value	Description	Default
features.aws.enabled	When true, enables image fetching from Amazon S3 buckets	false
features.aws.accountId	AWS account ID (for authentication via IAM Role)
features.aws.iamRoleName	the name of IAM Role used for authentication
features.aws.accessKeyId	AWS Access Key ID
features.aws.secretAccessKey	AWS Secret Access Key
features.aws.s3Region	AWS Region
features.aws.s3Endpoint	Custom S3 endpoint to being used by imgproxy

Google Cloud Storage support

Value	Description	Default
features.gcs.enabled	When true, enables image fetching from Google Cloud Storage	false
features.gcs.jsonKey	Google Cloud JSON key. When set, enables image fetching from Google Cloud Storage buckets
features.gcs.endpoint	A custom Google Cloud Storage endpoint to being used by imgproxy.

MS Azure Blob Storage support

Value	Description	Default
features.abs.enabled	when true, enables image fetching from Azure Blob Storage containers	false
features.abs.accountName	Azure storage account name
features.abs.accountKey	Azure storage account key
features.abs.endpoint	custom Azure Blob Storage endpoint to being used by imgproxy

Integration to the New Relic

Value	Description	Default
features.newRelic.enabled	Enables New Relic integration	false
features.newRelic.licenseKey	New Relic license key
features.newRelic.appName	New Relic application name

Error Reporting

Value	Description	Default
features.errorReporting.bugsnag.enabled	Enable integration with Bugsnag	false
features.errorReporting.bugsnag.key	Bugsnag API key. When provided, enables errors reporting to Bugsnag
features.errorReporting.bugsnag.env	Bugsnag stage to report to
features.errorReporting.honeybadger.enabled	Enable integration with Honeybadger	false
features.errorReporting.honeybadger.key	Honeybadger API key.
features.errorReporting.honeybadger.env	Honeybadger env to report to	production
features.errorReporting.sentry.enabled	Enable integration with Sentry	false
features.errorReporting.sentry.dsn	Sentry project DSN.
features.errorReporting.sentry.env	Sentry environment to report to	production
features.errorReporting.sentry.release	Sentry release to report to	imgproxy/{imgproxy version}
features.errorReporting.reportDownloadingErrors	when true, imgproxy will report downloading errors	true

Logging

Value	Description	Default
features.logging.format	the log format. The following formats are supported: ['pretty', 'structured', 'json']	pretty
features.logging.level	the log level. The following levels are supported error, warn, info and debug	info
features.logging.syslog.enabled	when true, enables sending logs to syslog	false
features.logging.syslog.level	maximum log level to send to syslog. Known levels are: crit, error, warning and info	info
features.logging.syslog.network	network that will be used to connect to syslog. When blank, the local syslog server will be used. Known networks are tcp, tcp4, tcp6, udp, udp4, udp6, ip, ip4, ip6, unix, unixgram and unixpacket
features.logging.syslog.address	address of the syslog service. Not used if IMGPROXY_SYSLOG_NETWORK is blank.
features.logging.syslog.tag	specific syslog tag	imgproxy

Memory Usage Tweaks

Value	Description	Default
features.memoryUsageTweaks.downloadBufferSize	the initial size (in bytes) of a single download buffer. When zero, initializes empty download buffers	0
features.memoryUsageTweaks.gzipBufferSize	the initial size (in bytes) of a single GZip buffer. When zero, initializes empty GZip buffers. Makes sense only when GZip compression is enabled	0
features.memoryUsageTweaks.freeMemoryInterval	the interval (in seconds) at which unused memory will be returned to the OS.	10
features.memoryUsageTweaks.bufferPoolCalibrationThreshold	the number of buffers that should be returned to a pool before calibration	1024

Miscellaneous imgproxy Settings

Value	Description	Default
features.miscellaneous.baseUrl	base URL part which will be added to every requestsd image URL.
features.miscellaneous.useLinearColorspace	when true, imgproxy will process images in linear colorspace. This will slow down processing. Note that images won’t be fully processed in linear colorspace while shrink-on-load is enabled (see below)	false
features.miscellaneous.disableShrinkOnLoad	when true, disables shrink-on-load for JPEG and WebP. Allows to process the whole image in linear colorspace but dramatically slows down resizing and increases memory usage when working with large images	false
features.miscellaneous.stripColorProfile	when true, imgproxy will transform the embedded color profile (ICC) to sRGB and remove it from the image.	true
features.miscellaneous.autoRotate	when true, imgproxy will auto rotate images based on the EXIF Orientation parameter (if available in the image meta data).	true
features.miscellaneous.stripMetadata	whether to strip all metadata (EXIF, IPTC, etc.) from JPEG and WebP output images	true
features.miscellaneous.keepCopyright	When true, imgproxy will not remove copyright info while stripping metadata	true
features.miscellaneous.enforceThumbnail	When true and the source image has an embedded thumbnail, imgproxy will always use the embedded thumbnail instead of the main image. Currently, only thumbnails embedded in heic and avif are supported.	false
features.miscellaneous.healthCheck.message	The content of the health check response
features.miscellaneous.healthCheck.path	An additional path of the health check.

k8s deployment

Deployment specific options.

Value	Description	Default
image.pullSecrets.password	Password to your private registry	``
image.pullSecrets.registry	URL of a private registry you want to authorize to	``
image.pullSecrets.username	Login to your private registry	``
image.addPullSecrets	List of existing image pull secrets	[]
resources.deployment.affinity	Node and inter-pod affinity configuration
resources.deployment.annotations	Custom annotations for imgproxy deployment	{}
resources.pod.annotations	Custom annotations for imgproxy pod	{}
resources.pod.labels	Custom labels for imgproxy pods	{}
resources.deployment.readinessProbe	Timeouts and counters for the readiness probe
resources.deployment.livenessProbe	Timeouts and counters for the liveness probe
resources.deployment.nodeSelector	A node selector labels
resources.deployment.priority.name	The name of the priority class
resources.deployment.priority.level	The level of the pod priority	0
resources.deployment.priority.preempting	If the pod should be preempting (k8s v1.19+)	true
resources.podDisruptionBudget.enabled	Enable or disable a disruption budget policy	false
resources.podDisruptionBudget.maxUnavailable	maxUnavailable option for the PodDisruptionBudget	0
resources.podDisruptionBudget.minAvailable	minAvailable option for the PodDisruptionBudget	0
resources.deployment.replicaCount	How many pods with imgproxy should be running simultaneously (DEPRECATED, use replicas.default instead!)	1
resources.deployment.replicas.default	How many pods with imgproxy should be running after deployment	1
resources.deployment.replicas.minCount	The minimal number of pods the imgproxy can be scaled to.	1
resources.deployment.replicas.maxCount	The maximum number of pods the imgproxy can be scaled to.	1
resources.deployment.replicas.stepCount	The max number of pods to be added/dropped during autoscaling step.	1
resources.deployment.replicas.stepSeconds	The period in seconds (1-1800) during which up to stepCount pods can be added or dropped by autoscaler.	60
resources.deployment.replicas.stabilizationInterval	The number of seconds for which past recommendations should be considered while scaling up or scaling down (0 - 3600) to prevent flapping.	300
resources.deployment.replicas.cpuUtilization	The target percentage for the average CPU utilization by pods after which they should be scaled.	80
resources.deployment.resources	Hash of resource limits for your pods	{}
resources.deployment.tolerations	Tolerations for Kubernetes taints
resources.serviceAccount.annotations	Annotations for the Kubernetes service account for imgproxy	``
resources.service.type	Kubernetes service type for imgproxy	ClusterIP
resources.service.loadBalancerIP	Load balancer ip for service type "LoadBalancer"	''
resources.service.loadBalancerSourceRanges	Load balancer source ranges for service type "LoadBalancer"	`[]
resources.service.externalTrafficPolicy	Enable client source IP preservation	Cluster

Ingress configuration

Value	Description	Default
resources.ingress.acme	Enables the ingress resource annotation which tells cert-manager to issue a Let's Encrypt certificate	false
resources.ingress.annotations	Additional annotations for the ingress resource
resources.ingress.enabled	When true, enables ingress resource for imgproxy	false
resources.ingress.health.whitelist	Comma separated string of CIDR addresses that are allowed to access /health url of imgproxy
resources.ingress.hosts	Hostnames for the ingress resource to use	["example.com"]
resources.ingress.tls	TLS config array
resources.ingress.tls[].hosts	Hostnames this tls secret is used for	["example.com"]
resources.ingress.tls[].secretName	Name of the k8s Secret resource which stores crt & key for the ingress resource

Monitoring

Options to configure ServiceMonitor for Prometheus Operator.

Value	Description	Default
features.prometheus.enabled	Set IMGPROXY_PROMETHEUS_BIND environment variable to bind metrics to port 8081	false
features.prometheus.namespace	Set IMGPROXY_PROMETHEUS_NAMESPACE environment variable to prepend prefix to the names of metrics	""
resources.serviceMonitor.honorLabels	Chooses the metric's labels on collisions with target labels	true
resources.serviceMonitor.interval	Interval at which metrics should be scraped (if it differs from default one)	0
resources.serviceMonitor.namespace	Namespace with PrometheusOperator	monitoring
resources.serviceMonitor.selector	Selector to select Pods	release: prometheus-operator
resources.serviceMonitor.targetLabels	Transfers mentioned labels on the Kubernetes Service onto the target	["app","release"]

See values.yaml for some more Kubernetes-specific configuration options.

Persistence

Options to mount a persistent volume.

Value	Description	Default
persistence.enabled	Enable persistence for deployment.	false
persistence.name	Set name for persistent volume claim.	imgproxy-data
persistence.existingClaim	Reference an existing PVC instead of creating a new one.	""
persistence.mountPath	Mount path for PVC in the imgproxy pod.	/images
persistence.subPath	Mount sub path of the persistent volume.	""
persistence.accessModes	Access modes for the persistent volume.	- ReadWriteOnce
persistence.size	Storage size of the PV.	10Gi
persistence.storageClass	Set the storageClass for the persistent volume claim.	""
persistence.dataSource	Create a PV from a data source (e.g. snapshot).	""

Other

Value	Description	Default
nameOverride	String to partially override imgproxy.fullname template with a string (will be appended to the release name)	nil
fullnameOverride	String to fully override imgproxy.fullname template with a string (will be used as pod name prefix instead of release name)	nil

You can also add custom env variables for the latest version of imgproxy:

# values.yml
---
# ...
features:
  # ...
  custom:
    FOO: bar

Notice, that all custom env variables are sent through the secret (encoded to base64 under the hood).