Asterisk Config is a kubernetes sidecar container which constructs the configuration for Asterisk. It is comprised of a custom configuration set and a standardized dynamic environment set to build the Asterisk configuration for the Pod in question.
The primary dynamic component of Asterisk Config is the IP address (internal and external) for use by the SIP and PJSIP modules.
Any time dynamic data is updated, Asterisk is told to reload. By default, we
only reload res_pjsip.so, since the dynamic data usually just involves PJSIP
endpoint IPs. However, you can set the RELOAD_MODULES environment variable to
a comma-separated list of modules which should be reloaded when the dynamic data
is updated.
The reloads are performed by executing the ARI "/asterisk/modules" "PUT" (reload) once for each of the specified modules. This ARI connection is automatically created with a randomly-generated password by Asterisk Config.
There are two layers of files which are used:
- Default configuration
- Custom configuration
Included within this package is the standard Asterisk basic configuration set with minimal alterations to:
- include custom configurations
- include configuration directories
- disable all file-based logging
Any file in the default configuration my be replaced by including it in your custom configuration bundle, but see the Custom configuration section below for better methods.
The default configuration also creates configurations for ARI, so that it may call a reload when necessary, and PJSIP, to configure the IP information for transports.
The following default PJSIP transports will be specified:
k8s-internal-ipv4-internal-media(internal SIP/signaling advertisement, internal RTP/media advertisement, port 5080/UDP)k8s-internal-ipv4-external-media(internal SIP/signaling advertisement, external RTP/media advertisement, port 5070/UDP)k8s-external-ipv4-external-media(external SIP/signaling advertisement, external RTP/media advertisement, port 5060/UDP)
In most cloud-based kubernetes setups, the Pod will be assigned an internal IP address, and it will have a NATed external IP address. The choice of transports depends on two things:
- Where is the signaling endpoint?
- Where is the media endpoint?
It is common, for instance, to use kamailio as a SIP proxy to handle a scalable
set of Asterisk servers. In this case, you would want to use internal
signaling IPs. The RTP, however, will depend on whether you want your media to
flow directly to your Asterisk Pods (-external-media) or by way of
rtpengine or rtpproxy (-internal-media).
For each of your PJSIP Endpoints, just specify the transport you wish to
use.
While your custom configurations are allowed to overwrite any Asterisk configuration file, there are generally two schemes by which customized configurations may be applied:
<module>.d/XXXX.conf<module>_custom.conf
The most flexible approach is to create any number of discrete files in the module configuration subdirectories. For instance, you might add a PJSIP endpoint configuration in:
pjsip.d/ext-101.conf
Any file with the .conf extension in one of these directories will
automatically be loaded.
Modules which are configured to load configurations using this scheme are:
- AMI (
manager.d/) - ARI (
ari.d/) - Extensions (
extensions.d/) - PJSIP (
pjsip.d/) - Voicemail (
voicemail.d/)
If there is any default configuration for any of these modules, that
configuration will exist in <extension>_custom.conf. The corresponding
<extension>.conf only contains include statements.
Take special note that ARI and PJSIP modules are used internally by Asterisk
Config, so changing their root ari.conf and pjsip.conf is not recommended
unless you really know what you are doing.
It is presumed that you have a kubernetes installation on a standard cloud platform (such as AWS, GCP, Azure, DigitalOcean, etc) or are running a baremetal kubernetes cluster which you can control to supply the public and private IP addresses for the Asterisk Pod.
It is strongly recommended to set the CLOUD environment variable to match your
environment. The valid options are:
awsAmazon Web ServicesazureMicrosoft AzuredigitaloceanordoDigital OceangcpGoogle Cloud Platform- `` default discovery
Default discovery is useful for baremetal configurations or situations where you do not wish to use the cloud provider's self discovery API.
NOTE: Importantly, in cases where you need Asterisk to use the kubernetes
Pod IP address instead of the Node IP address, set the CLOUD variable to be
the empty string. Default discovery also works for public IP addresses by using
the jsonip.io service.
Asterisk Config offers varying levels of configuration complexity, allowing you to easily just get your Asterisk system off the ground or to build a fully-templated configuration set.
It is a common problem that Asterisk may start before the config has been
written. In order to eliminate that eventuality, you should check for the
existence of the .asterisk-config file before allowing Asterisk to start.
The simplest use is: to create the set of custom Asterisk configurations
- create the set of custom Asterisk configurations for your scenario
- generate a
.zipfile of that configuration tree - load that
.zipfile to a ConfigMap, Secret, or Web URL
For example:
We will define a simple dialplan with a single PJSIP endpoint to a carrier. When a call comes in from the carrier, it will be answered and any audio received will be played back to the caller.
First, create a directory to contain the configuration files. Files stored in
this directory will be copied into /etc/asterisk/ on the live Asterisk Pod.
In this example, we will use the local directory named
/home/user/asterisk/config.
Inside your directory, we create two files: pjsip.d/my_carrier.conf and
extensions.d/dialin.conf.
pjsip.d/my_carrier.conf:
[pstn]
type=endpoint
transport=k8s-external-ipv4-external-media
context=dialin
disallow=all
allow=ulaw
aors=pstn
rtp_symmetric=yes
[pstn]
type=aor
contact=sip:my.carrier.com:5060
[pstn]
type=identify
endpoint=pstn
match=12.34.56.78
match=87.65.43.21
[acl]
type=acl
deny=0.0.0.0/0.0.0.0
permit=12.34.56.78/255.255.255.255
permit=87.65.43.21/255.255.255.255extensions.d/dialin.conf:
[dialin]
exten = echo,1,Verbose(1, "Running Echo")
same = n,Answer()
same = n,Echo()
same = n,Hangup()
exten = 15555555555,1,Verbose(1, "Received call to +1 555 555.5555")
same = n,Goto(echo,1)Now zip up these configuration files to a new asterisk-config.zip:
zip -r asterisk-config.zip *Then store the asterisk-config.zip file to kubernetes as a Secret named
"asterisk-config":
kubectl create secret generic asterisk-config --from-file=asterisk-config.zipNOTE: By default, Asterisk-Config looks for the Secret named "asterisk-config" to load the custom configuration. See the section below for sourcing the custom configuration from a different location.
Now we create a normal Pod spec for kubernetes including the Asterisk Configuration sidecar container:
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: asterisk
labels:
component: asterisk
spec:
replicas: 1
template:
metadata:
labels:
component: asterisk
spec:
hostNetwork: true
containers:
- name: config
image: ghcr.io/cycoresystems/asterisk-config
env:
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
volumeMounts:
- name: config
mountPath: /etc/asterisk
- name: source
mountPath: /source
- name: asterisk
image: cycoresystems/asterisk
volumeMounts:
- name: config
mountPath: /etc/asterisk
volumes:
- name: config
- name: source
secret:
secretName: "asterisk-config"By default, Asterisk Config looks for the file /source/asterisk-config.zip as
the source of configuration. However, this can be customized by setting the
SOURCE environment variable.
You may also obtain the source from an HTTP URL by specifying that URL as the
SOURCE. Additional environment variables may be provided for HTTP authentication:
URL_USERNAME(for basic authentication)URL_PASSWORD(for basic authentication),URL_AUTHORIZATION(explicit"Authorization" header)
If no SOURCE file can be found or is specified, Asterisk Config will attempt to
load the (expanded) configuration tree in the /custom/ directory. In this
way, you may plug in your own source-obtaining method and have it populate the
custom configuration files in this directory.
To make sure the Asterisk container is not successfully started before the configuration can be loaded, Asterisk Config will die if no valid custom configuration can be obtained. Asterisk will already die if it cannot find its configuration. Kubernetes will automatically restart each of these if they die.
Asterisk Config will process any file within the source bundle which ends in the
.tmpl extension. These files will be processed as Go text/template
files and the output stored as the same filename without the .tmpl extension.
Values for the templates may come from a number of sources:
- ConfigMap
- Environment Variables
- Service
- Endpoints (of a Service)
- EndpointIPs (of a Service)
- Network
To obtain ConfigMap entries, Asterisk Config will use the Kubernetes API to attempt to pull in the ConfigMap and key requested.
Format: {{.ConfigMap "<name>" "<namespace>" "<key>"}}
The provided namespace may be "" if both the ConfigMap is in the same
namespace as the Pod and the POD_NAMESPACE environment variable is properly
set.
The ConfigMap will be monitored by Asterisk Config, and if it is updated, the configuration files will be regenerated, and a reload will be performed.
Note that this will likely require an RBAC entry to allow the ServiceAccount
under which Asterisk Config is running to access the referenced ConfigMap.
Format: {{.Env "<name>"}}
It is useful to note that IP addresses of services within the same namespace
will automatically be populated as environment variables by kubernetes. These
will be of the form <SERVICE_NAME>_SERVICE_HOST. For instance, the IP of a
service named "kamailio" will be stored in the environment variable
KAMAILIO_SERVICE_HOST. This is a normal, default feature of all kubernetes
containers. See the documentation for more information.
Data from a kubernetes Service may be obtained using the Kubernetes API.
Format: {{.Service "<name>" "<namespace>]"}}
The provided namespace may be "" if both the Service is in the same
namespace as the Pod and the POD_NAMESPACE environment variable is properly
set.
The value returned here is the Kubernetes Service. Keep in mind that Go uses PascalCase for the fields, so "clusterIP" becomes "ClusterIP".
For example, to get the ClusterIP of a service named "kamailio" in the "voip" namespace:
{{ with .Service "kamailio" "voip"}}{{.Spec.ClusterIP}}{{end}}
Note that the IP address of a service within the same namespace can be obtained more simply by environment variable, as described above.
Data from the kubernetes Endpoints of a Service may be obtained using the Kubernetes API.
Format: {{.Service "<name>" "<namespace>"}}
The provided namespace may be "" if both the Service is in the same
namespace as the Pod and the POD_NAMESPACE environment variable is properly
set.
The value returned is the Kubernetes Endpoints.
The Endpoints will be monitored by Asterisk Config, and if it is updated, the configuration files will be regenerated, and a reload will be performed.
This is usually used to obtain the dynamic set of proxy servers, but since the most common reason to do this is to obtain the set of IPs for endpoints of a service, we provide a second helper function just for that.
One of the most common pieces of dynamic data to retrieve is the set of IPs for the endpoints of a service. Therefore, to simplify the relatively tedious iteration of these directly from the Endpoints spec, we provide the EndpointIPs macro, which returns the list of IPs of all Endpoints of the given service name.
Format: {{.EndpointIPs "<name>" "<namespace>"}}
The provided namespace may be "" if both the Service is in the same
namespace as the Pod and the POD_NAMESPACE environment variable is properly
set.
Using this is then easy. For example, to create a PJSIP endpoint from the set of proxy servers running as the "kamailio" service:
pjsip.d/proxies.conf:
[proxies]
type=endpoint
transport=k8s-internal-ipv4-external-media
context=from-proxies
disallow=all
allow=ulaw
aors=proxies
rtp_symmetric=yes
[proxies]
type=aor
{{range .EndpointIPs "kamailio"}}
contact=sip:{{.}}
{{end}}
[proxies]
type=identify
endpoint=proxies
{{range .EndpointIPs "kamailio"}}
match={{.}}
{{end}}
[proxies]
type=acl
deny=0.0.0.0/0.0.0.0
{{range .EndpointIPs "kamailio"}}
permit={{.}}
{{end}}The Endpoints IPs will be monitored by Asterisk Config, and if they are updated, the configuration files will be regenerated, and a reload will be performed.
The IP addresses for the running Pod are made available, as well.
Format: {{.Network "<kind>"}}
The available data kinds correspond to the data available from NetDiscover:
- "hostname"
- "privatev4"
- "publicv4"
- "publicv6"
Note that PJSIP transports are already automatically set up, as described above.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent