This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

AgileTV CDN Manager (esb3027)

Centralized Management of AgileTV CDN Director

1: Introduction to AgileTV CDN Manager
2: Installation
3: Releases

3.1: Release esb3027-1.0.0

4: Glossary

1 - Introduction to AgileTV CDN Manager

A brief overview of AgileTV CDN Manager

The ESB3027 AgileTV CDN Manager is a suite of software designed to facilitate the coordination of one or more instances of ESB3024 AgileTV CDN Director. It provides services and common functionality which are shared between independent routers such as user identity management, API services, and common messaging and data persistence.

The Manager software is deployed locally using a self-hosted Kubernetes orchestration framework. Kubernetes provides many advantages out of the box including automatic horizontal scaling, load-balancing, service monitoring, persistent data storage, and a Cloud-Native deployment infrastructure.

The installer for ESB3027 AgileTV CDN Manager automatically deploys a lightweight Kubernetes implementation using Rancher K3s, along with all necessary tools to manage the cluster.

For the 1.0 release of ESB3027 AgileTV CDN Manager, only one supported configuration is provided. This configuration requires a single physical or virtual machine running Red Hat Enterprise Linux 8 or 9, or a compatible clone such as Oracle Linux. A minimum of 8GB of available RAM is required to deploy the software. During the installation process, one or more packages may be required from the software repositories provided by the Operating System. If the official repositories cannot be reached, the original ISO must be properly mounted such that package installation can be performed.

One additional prerequisite for the installation is a Fully-Qualified Domain Name that is DNS-resolvable and points to the node. This must be set up prior to installing the software, and all APIs must use this DNS name. Attempting to access any APIs via an IP address may result in failures due to Cross-Origin Resource Sharing protections which are enforced.

Please ensure that at a minimum, you are familiar with the terminology from the Glossary.

Quickstart Guide

This guide will give a quick overview of the basic installation procedure. This guide will focus on the basic procedure, for an in-depth overview of each step in the procedure, see the Installation Guide.

Preparation

Make sure SELinux and Firewalld are disabled and the ESB3027 AgileTV CDN Manager ISO is mounted. For this guide we are assuming that the ISO is mounted on /mnt however, any mountpoint may be used.

Install the Cluster

Start by installing the Kubernetes cluster by running the installer script.

/mnt/install.sh

Generate the Configuration Template

There are several scripts available on the ISO which are used to prepare the configuration template. All take a wizard based approach, prompting the user to provide information.

Create an SSL Certificate Secret (Optional)

If you have valid SSL certificates that should be used in place of the built-in self-signed certificates, you will need both the certificate and key files present on the node, and to run the script /mnt/load-certificates.sh. This will generate a Kubernetes Secret containing the certificates.

Generate the Zitadel Masterkey (Optional)

It is recommended to generate a unique Master Key used by Zitadel to protect sensitive information at rest. This can be accomplished using the ./mnt/load-zitadel-key.sh script. This will generate a cryptographically secure key and create the corresponding Kubernetes secret containing this value.

Generate the Configuration Template

Once you have prepared all the necessary values, running the /mnt/configure.sh script will generate a file values.yaml in the current directory. Be sure to inspect this file before proceeding. Verify that all required fields are correctly populated, such as the addresses of routers, API endpoints, and other components like the Configuration GUI. Additionally, ensure that any necessary sections are uncommented and that the file adheres to the expected format for successful deployment.

Deploy the Software

After generating the values.yaml file in the previous section, install the “acd-manager” Helm chart using the following command:

helm upgrade --install acd-manager --values values.yaml --atomic --timeout=10m /mnt/helm/charts/acd-manager

When this command returns, all pods in the deployment should be marked ready, and the ESB3027 AgileTV CDN Manager installation is complete. You can verify the state of the cluster with kubectl.

kubectl get pods

2 - Installation

Installation Procedure

Prerequisites

One or more physical or virtual machines running RedHat Enterprise Linux 8 or 9 or compatible operating system.
A minimum of 8GB available RAM
A resolvable fully-qualified DNS hostname pointing to the node.

ESB3027 AgileTV CDN Manager 1.0 is only supported in a single-node self-hosted configuration.

For the 1.0 Release of ESB3027 AgileTV CDN Manager, the following limitations are in place:

Only a single-node, self-hosted cluster configuration is supported.
The release does not support firewalld or SELinux in enforcing mode. These services MUST be disabled before starting.

sed -i 's/^SELINUX=.*/SELINUX=permissive/' /etc/selinux/config
setenforce 0
systemctl disable --now firewalld

Installing the software depends on several binaries that will be placed in the /usr/local/bin directory on the node. On RHEL based systems, if a root shell is obtained using sudo, that directory will not be present in the path. Either you must configure sudo to not exclude that directory from the path, or use su - which does not exhibit this behavior. You can verify if that directory is included in the path with the following command:

echo $PATH | grep /usr/local/bin

Installing the Manager

The following procedure will assume that the latest ISO for the Manager has been copied to the node.

Mount the ESB3027 ISO. For this example, we are assuming that the ISO will be mounted on /mnt but any mountpoint may be used. Substitute the actual mountpoint for /mnt in all following commands.

mount -o loop,ro esb3027-acd-manager-1.0.0.iso /mnt

Run the install.sh script from the ISO.

/mnt/install.sh

Generating the Configuration

The following instructions should all be executed from the primary node unless otherwise specified.

Loading SSL Certificates (Optional)

If you wish to include valid SSL certificates for the Manager, you must first load them into a Kubernetes Secret. A helper script load-certificates.sh has been provided on the ISO to read the Certificate and Key files and create the Kubernetes Secret for you. If this is not performed, the Manager will generate and use a self-signed certificate automatically.

The load-certificates.sh script uses a simple wizard approach to prompt for the files containing the SSL certificate and SSL Private Key file, and the name of the secret. The name can be any string containing alpha-numeric characters and either - or _.

/mnt/load-certificates.sh

Enter the path to the SSL Certificate File: /root/example.com.cert
Enter the path to the SSL Key File: /root/example.com.key
Enter the name of the secret containing the SSL Certificate and Key (e.g. my-ssl-certs): example-com-ssl-key
secret/example-com-ssl-key created

Generating the Zitadel Masterkey (Optional)

Zitadel is a User Identity Management software used to manage authentication across the system. Certain data in Zitadel such as credential information needs to be kept secure. Zitadel uses a 32-byte cryptographic key to protect this information at rest, and highly recommends that this key be unique to each environment.

If this step is not performed, a default master key will be used instead. Using a hardcoded master key poses significant security risks, as it may expose sensitive data to unauthorized access. It is highly recommended to not skip this step.

The load-zitadel-key.sh script generates a secure 32-byte random key and loads that key into a Kubernetes Secret for Zitadel to use. This step should only be performed once, as changing the key will result in all encrypted credential information being unrecoverable. For the secret name, any string containing alpha-numeric characters and either - or _ is allowed.

/mnt/load-zitadel-key.sh

Enter the name of the secret containing the Zitadel Masterkey (e.g. my-zitadel-key): zitadel-key
secret/zitadel-key created

Generating the Configuration Template

The last step prior to installing the Manager software is to generate a values.yaml file, which is used by Helm to provide configuration values for the deployment, to configure the installation. This can be performed by running the script configures.sh on the ISO. This script will prompt the user for a few pieces of information, including the “external domain” which is the DNS resolvable fully-qualified domain name which must be used to access the manager software, and the optional names of the secrets generated in the previous sections. Ensure that sufficient write privileges exist to write to the current directory.

/mnt/configure.sh

Enter the domain you want to use for Zitadel (e.g. zitadel.example.com): manager.example.com
Enter the name of the secret containing the SSL Certificate and Key (e.g. my-ssl-certs): example-com-ssl-key
Enter the name of the secret containing the Zitadel Masterkey (e.g. my-zitadel-key): zitadel-key
Wrote /root/values.yaml

After running this wizard, a values.yaml file will be created in the current directory. Within this file, there is a commented out section containing the routers, gui, and geoip addresses. This should optionally be filled out before continuing so that it resembles the following structure.

NOTE: This file is YAML, and indentation and whitespace are part of the format. It is recommended before continuing, that you paste the contents of the file into an online YAML validator to ensure that the syntax is OK. You can use tools like yamllint.com or any other trusted YAML validator.

gateway:
  configMap:
    annotations: []
    routers:
      - name: router1
        address: 10.16.48.100
      - name: router2
        address: 10.16.48.101
    gui:
      host: 10.16.48.100
      port: 7001
    geoip:
      host: 10.16.48.100
      port: 5003
  ingress:
    tls:
      - hosts:
        - 10.16.48.140.sslip.io
        secretName: null

Deploying ESB3027 AgileTV CDN Manager

The ESB3027 software is deployed using Helm.

helm install acd-manager \
    --values values.yaml \
    --atomic \
    --timeout=10m \
    /mnt/charts/helm/acd-manager \

The use of the --atomic and --timeout flags will cause Helm to wait up to 10 minutes for all pods to be in the Ready state. For example, a timeout might occur if there are insufficient resources available in the cluster or if a misconfiguration, such as incorrect environment variables or missing secrets, prevents a pod from starting. If the timeout is reached before all pods are Ready, the entire installation will be automatically rolled back.

Updating the Deployment

In order to update an existing Helm deployment, whether to modify configuration values, or to upgrade to a newer software version, you must use the helm upgrade command. The syntax of this command is exactly the same as for helm install, and the same parameters used at install time must be provided. A shortcut option exists for the helm upgrade command --install which if supplied, will upgrade an existing deployment or install a new deployment if one is not already present.

helm upgrade acd-manager \
    /mnt/charts/helm/acd-manager \
    --values values.yaml \
    --atomic \
    --timeout 10m

Verifying the Installation

Verify the Ready status of the Running pods with the following command.

$ kubectl get pods
NAME                                           READY   STATUS      RESTARTS      AGE
acd-manager-gateway-6d489c5c66-jb49d           1/1     Running     0             20h
acd-manager-gateway-test-connection            0/1     Completed   0             17h
acd-manager-kafka-controller-0                 1/1     Running     0             20h
acd-manager-redis-master-0                     1/1     Running     0             20h
acd-manager-rest-api-668d889b76-sn2v4          1/1     Running     0             20h
acd-manager-selection-input-5fc9f4df4c-qz5mw   1/1     Running     0             20h
acd-manager-zitadel-ccb5d9674-9qpn5            1/1     Running     0             20h
acd-manager-zitadel-init-6l8vg                 0/1     Completed   0             20h
acd-manager-zitadel-setup-bmbh9                0/2     Completed   0             20h
postgresql-0                                   1/1     Running     0             20h

Each pod in the output contains a Ready status. This represents the number of pod replicas which are in the Ready state, as compared to the number of desired replicas provisioned by the deployment. Pods marked as “Completed” are typically one-time jobs or initialization tasks that have run to completion and finished successfully.

3 - Releases

ESB3027 AgileTV CDN Manager releases

3.1 - Release esb3027-1.0.0

Build date

2025-04-17

Release status

Type: production

Compatibility

This release is compatible with the following product versions:

AgileTV CDN Director, ESB3024-1.20.0

Breaking changes from previous release

None

Change log

This is the first production release

Deprecations from previous release

None

System requirements

A minimum CPU architecture level of x86-64-v2 due to inclusion of Oracle Linux 9 inside the container. While all modern CPUs support this archetecture level, virtual hypervisors may default to a CPU type that has more compatibility with older processors. If this minimum CPU architecture level is not attained the containers may refuse to start. See Operating System Compatibility and Building Red Hat Enterprise Linux 9 for the x86-64-v2 Microarchitecture Level for more information.

Known limitations

Installation of the software is only supported using a self-hosted, single-node configuration.

4 - Glossary

ESB3027 AgileTV CDN Manager definitions of commonly used terms

Access Token: A credential used to authenticate and authorize access to resources or APIs on behalf of a user, usually issued by an authorization server as part of an OAuth 2.0 flow. It contains the necessary information to verify the user’s identity and define the permissions granted to the token holder.
Bearer Token: A type of access token that allows the holder to access protected resources without needing to provide additional credentials. It’s typically included in the HTTP Authorization header as Authorization: Bearer <token>, and grants access to any resource that recognizes the token.
Chart: A Helm Chart is a collection of files that describe a related set of Kubernetes resources required to deploy an application, tool, or service. It provides a structured way to package, configure, and manage Kubernetes applications.
Cluster: A group of interconnected computers or nodes that work together as a single system to provide high availability, scalability and redundancy for applications or services. In Kubernetes, a cluster usually consists of one primary node, and multiple worker or agent nodes.
Confd: An AgileTV backend service that hosts the service configuration. Comes with an API, a CLI and a GUI.
ConfigMap (Kubernetes): A Kubernetes resource used to store non-sensitive configuration data in key-value pairs, allowing applications to access configuration settings without hardcoding them into the container images.
Containerization: The practice of packaging applications and their dependencies into lightweight portable containers that can run consistently across different computing environments.
Deployment (Kubernetes): A resource object that provides declarative updates to applications by managing the creation and scaling of a set of Pods.
Director: The AgileTV Delivery OTT router and related services.
ESB: A software bundle that can be separately installed and upgraded, and is released as one entity with one change log. Each ESB is identified with a number. Over time, features and functions within an ESB can change.
Helm: A package manager for Kubernetes that simplifies the development and management of applications by using pre-configured templates called charts. It enables users to define, install, and upgrade complex applications on Kubernetes.
Ingress: A Kubernetes resource that manages external access to services within a cluster, typically HTTP. It provides routing rules to manage traffic to various services based on hostnames and paths.
K3s: A lightweight Kubernetes cluster developed by Rancher Labs. This is a complete Kubernetes system deployed as a single portable binary.
K8s: A common abbreviation for Kubernetes.
Kafka: Apache Kafka is an open-source distributed event streaming platform designed for building real-time data pipelines and streaming applications. It enables the publication, subscription, storage, and processing of streams of records in a fault-tolerant and scalable manner.
Kubectl: The command-line tool for interacting with Kubernetes clusters, allowing users to deploy applications, manage cluster resources, and inspect logs or configurations.
Kubernetes: An open-source container orchestration platform designed to automate scaling, and management of containerized applications. It enables developers and operations teams to manage complex applications consistently across various environments.
LoadBalancer: A networking tool that distributes network traffic across multiple servers or Pods to ensure no single server becomes overwhelmed, improving reliability and performance.
Manager: The AgileTV Management Software and related services.
Namespace: A mechanism for isolating resources within a Kubernetes cluster, allowing multiple teams or applications to coexist without conflict by providing a scope for names.
OAuth2: An open standard for authorization that allows third-party applications to gain limited access to a user’s resources on a server without exposing the user’s credentials.
Pod: The smallest deployable unit in Kubernetes that encapsulates one or more containers, sharing the same network and storage resources. It serves as a logical host for tightly coupled applications, allowing them to communicate and function effectively within a cluster.
Router: Unless otherwise specified, an HTTP router that manages an OTT session using HTTP redirect. There are also ways to use DNS instead of HTTP.
Secret (Kubernetes): A resource used to store sensitive information, such as passwords, API keys, or tokens in a secure manner. Secrets are encoded in base64 and can be made available to Pods as environment variables or mounted as files, ensuring that sensitive data is not exposed in the application code or configuration files.
Service (Kubernetes): An abstraction that defines a logical set of Pods and a policy to access them, enabling stable networking and load balancing to ensure reliable communication among application components.
Session Token: A session token is a temporary, unique identifier generated by a server and issued to a user upon successful authentication.
Stateful Set (Kubernetes): A Kubernetes deployment which guarantees ordering and uniqueness of Pods, typically used for applications that require stable network identities and persistent storage such as with databases.
Topic (Kafka): A category or feed name to which records (messages) are published. Messages flow through a topic in the order in which they are produced, and multiple consumers can subscribe to the stream to process the records in real time.
Volume (Kubernetes): A persistent storage resource in Kubernetes that allows data to be stored and preserved beyond the lifecycle of individual Pods, facilitating data sharing and durability.
Zitadel: An open-source identity and access management (IAM) platform designed to handle user authentication and authorization for applications. It provides features like single-sign-on (SSO), multi-factor authentication (MFA), and support for various authentication protocols.